FileSystemFileHandle: createSyncAccessHandle() method

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

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

InvalidStateError DOMException

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

NoModificationAllowedError DOMException

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

NotAllowedError DOMException

Thrown if the permission has not been granted at the API level (i.e. FileSystemHandle.requestPermission is required).

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