FileSystemFileHandle: createSyncAccessHandle() method

Baseline 2023

Newly available

Since March 2023, this feature works across the latest devices and browser versions. This feature might not work in older devices or browsers.

Secure context: This feature is available only in secure contexts (HTTPS), in some or all supporting browsers.

Note: This feature is only available in Dedicated Web Workers.

The createSyncAccessHandle() method of the FileSystemFileHandle interface returns a Promise which resolves to a FileSystemSyncAccessHandle object that can be used to synchronously read from and write to a file. The synchronous nature of this method brings performance advantages, but it is only usable inside dedicated Web Workers for files within the origin private file system.

Creating a FileSystemSyncAccessHandle takes an exclusive lock on the file associated with the file handle. This prevents the creation of further FileSystemSyncAccessHandles or FileSystemWritableFileStreams for the file until the existing access handle is closed.

Syntax

js
createSyncAccessHandle()

Parameters

None.

Return value

A Promise which resolves to a FileSystemSyncAccessHandle object.

Exceptions

NotAllowedError DOMException

Thrown if the PermissionStatus.state for the handle is not granted in readwrite mode.

InvalidStateError DOMException

Thrown if the FileSystemSyncAccessHandle object does not represent a file in the origin private file system.

NotFoundError DOMException

Thrown if current entry is not found.

NoModificationAllowedError DOMException

Thrown if the browser is not able to acquire a lock on the file associated with the file handle.

Examples

The following asynchronous event handler function is contained inside a Web Worker. The snippet inside it creates a synchronous file access handle.

js
onmessage = async (e) => {
  // Retrieve message sent to work from main script
  const message = e.data;

  // Get handle to draft file
  const root = await navigator.storage.getDirectory();
  const draftHandle = await root.getFileHandle("draft.txt", { create: true });
  // Get sync access handle
  const accessHandle = await draftHandle.createSyncAccessHandle();

  // …

  // Always close FileSystemSyncAccessHandle if done.
  accessHandle.close();
};

Specifications

Specification
File System Standard
# api-filesystemfilehandle-createsyncaccesshandle

Browser compatibility

BCD tables only load in the browser

See also