API Improvements for working with files in the browser

Support for multiple readers and writers for FileSystemSyncAccessHandle and exclusive writer for FileSystemWritableFileStream.

Thomas Steiner

Multiple readers and writers for FileSystemSyncAccessHandle

The origin private file system (sometimes also referred to as the bucket file system) allows developers to access files that are optimized for maximum reading and writing performance. This happens via FileSystemSyncAccessHandle objects. Currently, trying to open multiple FileSystemSyncAccessHandle objects for the same file entry fails with a NoModificationAllowedError. Since there are use cases where this constraint is limiting, Chrome 121 introduces a new mode parameter for the FileSystemFileHandle.createSyncAccessHandle() method with the following allowed string values:

  • "readwrite": This is the current default. Once open, any methods on FileSystemSyncAccessHandle are allowed. Only one instance of FileSystemSyncAccessHandle is allowed.
  • "read-only" : Allows multiple readers. Once open, only read-like methods on FileSystemSyncAccessHandle are allowed: read(), getSize(), and close(). Multiple instances of FileSystemSyncAccessHandle may be created as long as all of them are in read-only mode.
  • "readwrite-unsafe": Allows multiple writers. Once open, any methods on FileSystemSyncAccessHandle are allowed. Multiple instances of FileSystemSyncAccessHandle may be created as long as all of them are in readwrite-unsafe mode.

The current behavior is preserved by keeping the "readwrite" option as the default, which only allows one instance at a time. If a site needs to open multiple FileSystemSyncAccessHandle objects but does not need to perform writes, then the "read-only" option should be used. Finally, the last option "readwrite-unsafe" allows multiple instances as well as both read and write. In this case, writes can be racy if performed from multiple tabs, and sites would need to provide their own locking scheme.

const handle1 = await handle.createSyncAccessHandle({mode: 'readwrite-unsafe'});
// This will succeed:
const handle2 = await handle.createSyncAccessHandle({mode: 'readwrite-unsafe'});

Exclusive writer for FileSystemWritableFileStream

Unlike with FileSystemSyncAccessHandle, multiple instances of FileSystemWritableFileStream can be created per file entry today. What's missing is a way to provide an option for an exclusive writer. Chrome 121 adds an optional mode parameter to the FileSystemAccessFileHandle.createWritable() method that has the following values:

  • "exclusive" mode: Only one writer can exist at a time.
  • "siloed" mode: This is the current default. Each created writer will have its own swap file.
const writable1 = await handle.createWritable({mode: 'exclusive'});
// This will fail:
const writable2 = await handle.createWritable();

Browser support

Both features, multiple readers and writers for FileSystemSyncAccessHandle and exclusive writer for FileSystemWritableFileStream, are supported as of Chrome 121.

Enter the dev trial

To enter the dev trial to test the feature before Chrome 121 launches, set the #file-system-access-locking-scheme flag in chrome://flags to Enabled. This will allow you to test the feature locally on your machine.

Acknowledgements

This article was reviewed by Daseul Lee, Nathan Memmott, and Rachel Andrew.