fsa-promises

Web File System API to Node fs promises API.

Learn more about: File System API

> [!NOTE]
> This library was originally implemented for use with isomorphic-git. But the actual test found that the performance was so bad and there were inexplicable problems, so I gave up. ☹️


Install

``bash


npm

npm install @tsuk1ko/fsa-promises

yarn

yarn add @tsuk1ko/fsa-promises

bun

bun add @tsuk1ko/fsa-promises
`

Usage

`ts
import { FsaPromises } from '@tsuk1ko/fsa-promises';

// Use navigator.storage.getDirectory() as root
const fs = new FsaPromises();

// Use directory "path/to/some/dir" of navigator.storage.getDirectory() as root,
// will be create recursively if not exists
const fs = new FsaPromises('path/to/some/dir');

// Use showDirectoryPicker() to select a directory as root
const fs = new FsaPromises(showDirectoryPicker({ mode: 'readwrite' }));

// Use almost the same way as node fsPromises module
await fs.writeFile('file.txt', 'hello world');
`

APIs

$3

options can be string, FileSystemDirectoryHandle, Promise or an FsaPromisesOptions object.

`ts
interface FsaPromisesOptions {
root?: string | FileSystemDirectoryHandle | Promise;
useSyncAccessHandleForFile?: boolean;
cacheDirHandle?: boolean;
}
`

#### useSyncAccessHandleForFile

When it is true, the library will use createSyncAccessHandle() instead of createWritable() to write file.

It is only usable inside dedicated Web Workers with the origin private file system.

For more information, please check here.

#### cacheDirHandle

Whether to enable directory handle cache.

When it is true, all FileSystemDirectoryHandle objects created at runtime will be cached until they are deleted via rmdir() or manually by calling clearDirCache().

This is useful when you need to frequently read or write files in deep directories, as it avoids creating new FileSystemDirectoryHandle objects layer by layer each time.

However, please note that if other processes are also operating on the file system, this may lead to unexpected behavior. For example, if a directory is deleted elsewhere, you may need to call clearDirCache() at the appropriate time.

$3

Refer to fsPromises.readFile.

flag and signal are not supported.

$3

Refer to fsPromises.writeFile.

mode is not supported.

flush is usable only when useSyncAccessHandleForFile is true.

signal is not usable when useSyncAccessHandleForFile is true.

#### options.ensureDir

This option is added for convenience and does not exist in the standard options.

When it is set to true, directories will be created recursively and automatically.

$3

Refer to fsPromises.unlink.

$3

Refer to fsPromises.readdir.

encoding only support undefine, null or "buffer".

$3

Refer to fsPromises.mkdir.

mode is not supported.

$3

Refer to fsPromises.rmdir.

maxRetries and retryDelay are not supported.

$3

This API does not exist in node fsPromises. It is provided for convenience.

$3

Refer to fsPromises.stat.

$3

Same as stat()` because symlink isn't implemented.

$3

Not implemented, don't use.

$3

Not implemented, don't use.

$3

Do nothing, just for compatibility.

$3

Clear directory handle cache.