FileSystem

Create and manage files in iOS and Android app sandboxes

One.FileSystem manages files in the iOS or Android app sandbox. It accepts absolute file:// URIs. Use getDirectories() for the Documents, Caches, Application Support, and temporary directories. On Android these are the app’s private files/Documents, cache, files, and cache/tmp directories. The returned directory URIs end in /.

import { One } from 'one'

const fs = One.FileSystem
const drafts = new URL('drafts/', fs.getDirectories().documents).href
const note = new URL('note.txt', drafts).href

await fs.makeDirectory(drafts)
await fs.writeFile(note, 'Hello One')
const text = await (await fetch(note)).text()
const info = await fs.getInfo(note)
console.log(text, info.size)

On native, use fetch(uri) to read text or bytes, including files returned by One.DocumentPicker and One.ImagePicker. writeFile(uri, contents) writes UTF-8 text and replaces an existing file. Pass 'base64' as the third argument to write binary data. Parent directories must already exist.

getInfo(uri) returns exists, isDirectory, byte size, and modifiedAt in Unix milliseconds. A missing path returns exists: false. readDirectory returns names, URIs, and directory flags. makeDirectory creates intermediate directories by default. copy and move fail if the destination exists. delete removes a file or directory recursively and fails if it is missing. The app’s home, Documents, Library, Caches, Application Support, and temporary root directories cannot be moved or deleted.

Operations run on a serial background queue. Calls awaited in sequence observe the previous operation’s result. A failed operation rejects with error.code: E_FILE_URI, E_FILE_ENCODING, E_FILE_NOT_FOUND, E_FILE_EXISTS, E_FILE_PERMISSION, or E_FILE_FAILED. File operations are implemented on iOS and Android. On web, files live in the Origin Private File System (OPFS), isolated by origin. Directory URIs use opfs://one/ and end in /. All operations, including reads and competing writes, run in order. A write resolves only after its writable stream closes. Browser storage quota, privacy policy, or an unavailable OPFS implementation can reject an operation. SSR keeps empty paths and inert operations. Base64 input must use standard padded base64 without line breaks.

OPFS URIs identify private storage entries; browser fetch and image elements do not understand them. To read stored bytes on web, use the browser’s navigator.storage.getDirectory() and its file handles. Documents, cache, application support, and temporary entries are folders within that origin’s OPFS; cache and temporary files are not automatically purged. Browser errors retain their DOMException names rather than the native error codes.