Web File System API to Node fs promises API.

Learn more about: File System API

# npm
npm install @tsuk1ko/fsa-promises

# yarn
yarn add @tsuk1ko/fsa-promises

# bun
bun add @tsuk1ko/fsa-promises

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');

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

interface FsaPromisesOptions {
  root?: string | FileSystemDirectoryHandle | Promise<FileSystemDirectoryHandle>;
  useSyncAccessHandleForFile?: boolean;
  cacheDirHandle?: boolean;
}

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.

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.

Refer to fsPromises.readFile.

flag and signal are not supported.

Refer to fsPromises.writeFile.

mode is not supported.

flush is usable only when useSyncAccessHandleForFile is true.

signal is not usable when useSyncAccessHandleForFile is true.

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.

Refer to fsPromises.unlink.

Refer to fsPromises.readdir.

encoding only support undefine, null or "buffer".

Refer to fsPromises.mkdir.

mode is not supported.

Refer to fsPromises.rmdir.

maxRetries and retryDelay are not supported.

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

Refer to fsPromises.stat.

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

Not implemented, don't use.

Not implemented, don't use.

Do nothing, just for compatibility.

Clear directory handle cache.