Files and folders
There are three ways to read and write files:
- Standard file pickers:
showOpenFilePicker,showSaveFilePicker,showDirectoryPicker,<input type="file">. No capability needed; you get whatever the user picks. acde:fs: files by "root": the app's own private folder, the shared folders it names (Downloads, Documents, ...), and folders the user picked. Suited to apps like file managers and editors. Requires thefscapability.- Private storage:
navigator.storage.getDirectory()(OPFS), IndexedDB,localStorage, for the app's own data.
An app works with handles and root ids, not with absolute paths; only the desktop and its bundled system apps see paths.
File pickers
Section titled “File pickers”They work just like in a browser:
const [handle] = await window.showOpenFilePicker({ types: [{ description: 'Markdown', accept: { 'text/markdown': ['.md'] } }],})const text = await (await handle.getFile()).text()- The dialog is the system's own (the open / save panel on macOS, the file dialog on Windows, the portal on Linux).
- Only this page can read and write the picked file.
- A folder picked with
showDirectoryPicker()is also granted to the app: it shows up as a root inacde:fs(source: 'granted') and is still there on the next launch. The default pick is read-only (the root hasmode: 'read_only');showDirectoryPicker({ mode: 'readwrite' })gives a writable one. Give it back withfs.revoke(id). - When the user cancels, the promise rejects with
AbortError. A headless session has no dialog: a picker rejects withAbortErrorthere too, unless a test answered it in advance (chooseFiles,chooseFolder,chooseSaveFile; see Testing).
acde:fs
Section titled “acde:fs”{ "capabilities": { "fs": true } }import { fs } from 'acde:fs'
const roots = await fs.roots()// [{ id: 'private', label: '…', source: 'private', mode: 'writable', reason: null, exists: true }]
await fs.writeFile('private', 'notes/todo.md', '- buy milk\n', { mkdirs: true })
const { entries } = await fs.list('private', 'notes')const { text, modifiedMs } = await fs.readText('private', 'notes/todo.md')await fs.writeFile('private', 'notes/todo.md', text + '- a new item\n', { ifModifiedMs: modifiedMs })The first argument of every call is a root's id, and the second is a path under that root. A root's id is an opaque name, not a path: fs.list('/home/me/Downloads') is rejected.
There are three kinds of root:
source |
id |
What it is | How the app gets it |
|---|---|---|---|
private |
private |
The app's own data folder, created on first use | "fs": true (or any fs value) |
place |
The place's name, such as downloads |
A shared folder of the user | Name it in fs.roots (see Shared places) |
granted |
folder- plus 16 hex digits |
A folder the user picked | showDirectoryPicker() |
roots() returns one item per root the app can use now: {id, label, source, mode, reason, exists}, plus place (the place's name) for a shared place. label is a name to show the user (the folder's name for a picked folder). mode is writable, read_only (a folder picked without mode: 'readwrite'), or unavailable; when it is unavailable, reason says why (the folder does not exist) and exists is false.
Find a picked folder's root by the handle's name:
const handle = await window.showDirectoryPicker({ mode: 'readwrite' })const picked = (await fs.roots()).find((root) => root.source === 'granted' && root.label === handle.name)await fs.writeFile(picked.id, 'export.txt', 'hello')Keep working data in private. It needs no declaration beyond fs and no picker, it is always writable, and it is not a root of any other app. Use a shared place or a picked folder only for files the user should find outside the app. On disk the private folder is $XDG_DATA_HOME/acde/files/<app id>/, which is handy when debugging; the app itself only knows it as private.
Shared places
Section titled “Shared places”{ "capabilities": { "fs": { "roots": ["downloads", "documents"] } } }fs.roots lists shared places by name: desktop, documents, downloads, music, pictures, videos. Anything else fails acdev check: fs.roots "work" is not a shared place (desktop, documents, downloads, music, pictures, videos); any other folder is one the user picks (showDirectoryPicker() with "fs": true), and for a path, fs.roots "~/Documents" is not a shared place: write "documents", the runtime finds that folder through the system (also when it was moved). private and picked folders come with every fs value and are not listed.
Declaring a place is what gives the app access to it; the user is not asked. Each named place is then in roots() as { id: 'downloads', source: 'place', place: 'downloads', … } and its id works as the first argument: fs.list('downloads'). When the folder does not exist on this machine, the root has mode: 'unavailable' and calls on it reject with ENOENT.
The second argument is a relative path under the root, separated by /; '' (or leaving it out in list) is the root itself. Absolute paths, and escaping the root with .. or a symbolic link, are rejected.
Common calls
Section titled “Common calls”| Call | Returns |
|---|---|
roots() |
The roots the app can use now |
list(root, path?, hidden?) |
{root, path, entries, truncated, skipped?}: folders first, at most 5000 entries (truncated); hidden entries (a leading dot, on Windows also the hidden or system attribute) only with hidden true; skipped counts entries whose names are not valid Unicode |
stat(root, path) |
{name, kind, size, modifiedMs, version, path} (does not follow symbolic links) |
readText(root, path) |
{text, modifiedMs, size, version}, up to 64 MiB, EILSEQ if not UTF-8 |
readBytes(root, path) |
{data: Uint8Array, modifiedMs, size, version}, up to 64 MiB |
writeFile(root, path, data, options?) |
Writes text or bytes, up to 64 MiB; returns the entry with its new version |
readRange(root, path, offset, length, {ifVersion}?) |
{data, offset, size, modifiedMs, version}: part of a file, at most 16 MiB at a time; size is the whole file's |
mkdir(root, path, {recursive?}) |
Creates a folder |
rename(root, from, to) |
Renames / moves inside one root |
delete(root, path) |
Deletes a file or an empty folder: {status: 'deleted', path} |
copy(fromRoot, fromPath, toRoot, toDir) |
Copies a file or a folder into the folder toDir of another root (or the same one); returns the new entry and its path. A taken name gets a number (todo 2.md) |
revoke(id) |
Gives back a folder the user picked |
To bring a file from a shared place or a picked folder into the app's own data, copy it: await fs.copy('downloads', 'report.txt', 'private', '').
Safe writes
Section titled “Safe writes”Options for writeFile:
create:'always'(default, creates the file if missing),'new'(EEXISTif it already exists),'never'(ENOENTif it does not exist).ifVersion: skips the write and fails withECONFLICTif the file is no longer the one you read. Every read returns aversion(an opaque string that tells two states of the file apart, even two writes in one millisecond); pass it when you write, and you will never overwrite someone else's changes.ifModifiedMsdoes the same with the modification time;ifVersionis the safer of the two. Neither goes withcreate: 'new'.mkdirs: creates the parent folders first. Without it, writing into a folder that does not exist fails withEINVAL.
A write replacing a file goes to a temporary file in the same folder first, is fsynced, and then replaces the file atomically (keeping its permissions; on Windows its attributes and ACL), so a crash leaves either the old or the new content. When the folder does not let the app create a file, it writes into the original file instead and the returned entry has inPlace: true: that write is not crash-safe.
Large files
Section titled “Large files”The whole-file calls stop at 64 MiB. For larger files use the standard handles: getFile() gives a File that reads on demand (slice(), stream()), and createWritable() writes at any position into a temporary file that close() puts in place atomically. acde:fs has the same as calls: readRange() above, and openWrite(root, path, {keepExistingData, create, ifVersion, mkdirs}?) → {id, size}, then writeChunk(id, offset, data) (at most 16 MiB a call), truncateWrite(id, size), and commitWrite(id) (returns the entry with its version) or abortWrite(id). With ifVersion, a change by someone else between the open and the commit is ECONFLICT and the file stays as it was. A write that is left alone for 10 minutes is given up.
Errors
Section titled “Errors”On failure the promise rejects with an Error that has a code and a status:
code |
status |
When |
|---|---|---|
EINVAL |
400 | Invalid arguments, an absolute path or one that escapes the root, a missing parent folder, wrong type, symbolic link |
EACCES |
403 | The first argument is not one of the app's roots, the root is read-only, or the system does not allow it |
ENOENT |
404 | Does not exist |
EEXIST |
409 | Already exists |
ECONFLICT |
409 | Changed or deleted by someone else since it was read (ifVersion, ifModifiedMs) |
ENOTEMPTY |
409 | Deleting a non-empty folder |
EFBIG |
413 | Exceeds the size limit |
EILSEQ |
400 | readText read something that is not UTF-8 |
ENOSPC |
507 | Disk full |
EIO |
500 | Anything else |
try { await fs.writeFile(root, path, text, { ifModifiedMs })} catch (e) { if (e.code === 'ECONFLICT') askToReload() else throw e}What the common mistakes look like:
| Mistake | Rejection |
|---|---|
A path as the root: fs.list('/tmp') |
EACCES: this app may not use the files of /tmp (not one of its roots) |
A place that is not in fs.roots: fs.list('downloads') with "fs": true |
EACCES: this app may not use the files of downloads (not one of its roots) |
An absolute path as the second argument: fs.readText('private', '/etc/hosts') |
EINVAL: path must be relative to the workspace |
.. out of the root: fs.readText('private', '../x') |
EINVAL: path escapes the workspace |
Writing into a folder that does not exist, without mkdirs |
EINVAL: parent directory is missing or outside the workspace |
Writing to a folder picked without mode: 'readwrite' |
EACCES: <folder> was picked read-only |
fs.locate(path) or fs.openPath(root, path) (they turn paths into roots and back) |
EACCES: fs.locate() works only in system apps that declare shared places |
Dropped files
Section titled “Dropped files”When files or folders are dragged from the host system into a window, the page receives the standard drag events, ending in drop, and dataTransfer carries the files the standard way. The page gets no path.
- Each dropped file or folder is an item of
dataTransfer.itemswithkind: 'file';item.getAsFileSystemHandle()resolves to a read-onlyFileSystemFileHandleorFileSystemDirectoryHandle(createWritable()rejects withNotAllowedError). - Files up to 64 MiB are also in
dataTransfer.files. Folders and larger files are not; use their handles. dataTransfer.typesis['Files']; there is notext/uri-listortext/plainwith the paths.
To keep a dropped file, copy its content into private:
import { fs } from 'acde:fs'
addEventListener('dragover', (event) => event.preventDefault())addEventListener('drop', async (event) => { event.preventDefault() const items = [...event.dataTransfer.items].filter((item) => item.kind === 'file') const handles = await Promise.all(items.map((item) => item.getAsFileSystemHandle())) for (const handle of handles) { if (handle.kind !== 'file') continue const file = await handle.getFile() await fs.writeFile('private', `inbox/${file.name}`, new Uint8Array(await file.arrayBuffer()), { mkdirs: true }) }})A handle (from a drop, a picker, or an open request) can also be handed to another app; see Opening apps.