File system
Public API
Item | Value |
|---|---|
Effect helper | ctx.effects.file_system() |
Location | FileSystemLocation::Path / FileSystemLocation::Directory |
Path | FileSystemPath |
Directory identity | DirectoryHandle / DirectoryHandleId |
Access and permission | FileSystemAccessMode / FileSystemPermission |
Entry metadata | FileSystemEntry / FileSystemEntryKind |
Write source | FileWriteSource::Bytes / FileWriteSource::Stream |
Error | FileSystemError |
CLI value | filesystem |
Operations
Method | Request | Success |
|---|---|---|
pick_directory | PickDirectoryRequest | PickDirectoryResult |
restore_directory | RestoreDirectoryRequest | RestoreDirectoryResult |
forget_directory | ForgetDirectoryRequest | () |
permission | DirectoryPermissionRequest | DirectoryPermissionResult |
list | ListDirectoryRequest | ListDirectoryResult |
stat | StatEntryRequest | StatEntryResult |
read | ReadFileRequest | ReadFileResult |
write | WriteFileRequest | WriteFileResult |
create_directory | CreateDirectoryRequest | () |
remove | RemoveEntryRequest | () |
release | ReleaseDirectoryRequest | () |
The corresponding capability constants use the same names in uppercase, including PICK_DIRECTORY, LIST_DIRECTORY, READ_FILE, and WRITE_FILE.
Locations and ownership
Handles are opaque, runtime-local values. They must not be persisted as integers or interpreted as paths. Persist an app-chosen key and ask restore_directory for a new live handle instead.
FileSystemLocation::path(path) addresses the active host filesystem directly. Native providers apply the process's normal operating-system permissions. Fission does not normalize or sandbox the path. Hosts without a global filesystem namespace return unsupported_path_namespace.
FileSystemLocation::directory(handle, path) addresses a provider path from an opaque handle. FileSystemLocation::directory_root(handle) addresses the handle itself. The provider determines which path forms and root operations its API can represent.
FileSystemAccessMode is a picker-provider request, not a Fission sandbox policy. Native operations are authorized by the operating system; browser and document providers enforce their host grants.
ReadFileResult::stream is a single-consumer runtime stream. FileWriteSource::Stream consumes its stream when the host opens it. Native and Web providers transfer data incrementally; the Web bridge uses bounded backpressure while adapting browser streams. WriteFileRequest::overwrite defaults to false so replacing user data requires an explicit choice.
Target behavior
Target | Behavior |
|---|---|
Web | Handle-backed access through showDirectoryPicker and FileSystemDirectoryHandle; direct host paths are unsupported. Optional handles are structured-cloned into IndexedDB. Requires a secure context and browser support. |
macOS, Windows, Linux | Direct OS paths plus the native folder picker. |
Android | Direct OS paths plus the system document-tree picker, persisted URI grants, and document-provider operations. |
iOS | Direct OS paths plus the system folder picker, security-scoped access, and persisted bookmarks. |
Terminal, Static site, SSR | No interactive directory provider. |
Web persistence stores only a granted browser handle. It is not an IndexedDB-backed virtual filesystem and it never copies the user's files. Browser permissions can return to prompt or denied after restoration.
Configuration
Run fission add-capability filesystem --project-dir .. This adds filesystem to fission.toml and the optional Fission Cargo feature. Direct native paths use the process's operating-system access. Picker-backed providers still require the host's user-selection and permission flow.
See the File system guide for reducer examples.
Previous
Clipboard
Next
Geolocation