https://github.com/tsuk1ko/fsa-promises
Web File System Access API to Node fs promises API
https://github.com/tsuk1ko/fsa-promises
file-system-access-api file-system-api node-fs
Last synced: 3 months ago
JSON representation
Web File System Access API to Node fs promises API
- Host: GitHub
- URL: https://github.com/tsuk1ko/fsa-promises
- Owner: Tsuk1ko
- License: mit
- Created: 2024-08-22T10:18:39.000Z (10 months ago)
- Default Branch: main
- Last Pushed: 2024-08-27T03:40:12.000Z (10 months ago)
- Last Synced: 2025-03-25T21:03:15.144Z (3 months ago)
- Topics: file-system-access-api, file-system-api, node-fs
- Language: TypeScript
- Homepage: https://www.npmjs.com/package/@tsuk1ko/fsa-promises
- Size: 26.4 KB
- Stars: 5
- Watchers: 1
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# fsa-promises
Web File System API to Node fs promises API.
Learn more about: [File System API](https://developer.mozilla.org/en-US/docs/Web/API/File_System_API)
> [!NOTE]
> This library was originally implemented for use with [isomorphic-git](https://github.com/isomorphic-git/isomorphic-git). But the actual test found that the performance was so bad and there were inexplicable problems, so I gave up. ☹️
[](https://www.npmjs.com/package/@tsuk1ko/fsa-promises)
## 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 '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
### `new FsaPromises([options])`
`options` can be `string`, `FileSystemDirectoryHandle`, `Promise` or an `FsaPromisesOptions` object.
```ts
interface FsaPromisesOptions {
root?: string | FileSystemDirectoryHandle | Promise;
useSyncAccessHandleForFile?: 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](https://developer.mozilla.org/en-US/docs/Web/API/FileSystemFileHandle/createSyncAccessHandle).
### `readFile(path[, options])`
Refer to [fsPromises.readFile](https://nodejs.org/api/fs.html#fspromisesreadfilepath-options).
`flag` and `signal` are not supported.
### `writeFile(file, data[, options])`
Refer to [fsPromises.writeFile](https://nodejs.org/api/fs.html#fspromiseswritefilefile-data-options).
`mode` is not supported.
`flush` is usable only when `useSyncAccessHandleForFile` is `true`.
`signal` is not usable when `useSyncAccessHandleForFile` is `true`.
### `unlink(path)`
Refer to [fsPromises.unlink](https://nodejs.org/api/fs.html#fspromisesunlinkpath).
### `readdir(path[, options])`
Refer to [fsPromises.readdir](https://nodejs.org/api/fs.html#fspromisesreaddirpath-options).
`encoding` only support `undefine`, `null` or `"buffer"`.
### `mkdir(path[, options])`
Refer to [fsPromises.mkdir](https://nodejs.org/api/fs.html#fspromisesmkdirpath-options).
`mode` is not supported.
### `rmdir(path[, options])`
Refer to [fsPromises.rmdir](https://nodejs.org/api/fs.html#fspromisesrmdirpath-options).
`maxRetries` and `retryDelay` are not supported.
### `exist(path)`
This API does not exist in node fsPromises. It is provided for convenience.
### `stat(path[, options])`
Refer to [fsPromises.stat](https://nodejs.org/api/fs.html#fspromisesstatpath-options).
### `lstat(path[, options])`
Same as `stat()` because symlink isn't implemented.
### `readlink(path[, options])`
Not implemented, don't use.
### `symlink(target, path[, type])`
Not implemented, don't use.
### `chmod(path, mode)`
Do nothing, just for compatibility.