add content for FileSystemSyncAccessHandle

files/en-us/web/api/file_system_access_api/index.md

@@ -16,6 +16,7 @@ browser-compat:
   - api.FileSystemHandle
   - api.FileSystemFileHandle
   - api.FileSystemDirectoryHandle
+  - api.FileSystemSyncAccessHandle
   - api.FileSystemWritableFileStream
   - api.Window.showOpenFilePicker
 ---
@@ -28,13 +29,16 @@ The File System Access API allows read, write and file management capabilities.
 
 This API allows interaction with files on a user's local device, or on a user-accessible network file system. Core functionality of this API includes reading files, writing or saving files, and access to directory structure.
 
-Most of the interaction with files and directories is accomplished through handles. A parent {{domxref('FileSystemHandle')}} class helps define two child classes: {{domxref('FileSystemFileHandle')}} and {{domxref('FileSystemDirectoryHandle')}}, for files and directories respectively.
+Most of the interaction with files and directories is accomplished through handles. A parent {{domxref('FileSystemHandle')}} class helps define two child classes: {{domxref('FileSystemFileHandle')}} and {{domxref('FileSystemDirectoryHandle')}}, for files and directories respectively. In addition, a third class—{{domxref('FileSystemSyncAccessHandle')}}—defines a handle for synchronous read/write operations. The synchronous nature of this class brings performance advantages intended for use in contexts where asynchronous operations come with high overhead (e.g., [WebAssembly](/en-US/docs/WebAssembly)), but it is only usable inside dedicated [Web Workers](/en-US/docs/Web/API/Web_Workers_API).
 
-These handles represent the file or directory on the user's system. You must first gain access to them by showing the user a file or directory picker. The methods which allow this are {{domxref('window.showOpenFilePicker')}} and {{domxref('window.showDirectoryPicker')}}. Once these are called, the file picker presents itself and the user selects either a file or directory. Once this happens successfully, a handle is returned. You can also gain access to file handles via the {{domxref('DataTransferItem.getAsFileSystemHandle()')}} method of the {{domxref('HTML Drag and Drop API')}}.
+The handles represent a file or directory on the user's system. You can first gain access to them by showing the user a file or directory picker. The methods which allow this are {{domxref('window.showOpenFilePicker')}} and {{domxref('window.showDirectoryPicker')}}. Once these are called, the file picker presents itself and the user selects either a file or directory. Once this happens successfully, a handle is returned. You can also gain access to file handles via the {{domxref('DataTransferItem.getAsFileSystemHandle()')}} method of the {{domxref('HTML Drag and Drop API')}}. In the case of {{domxref('FileSystemSyncAccessHandle')}}, the handle is accessed via the {{domxref('FileSystemFileHandle.createSyncAccessHandle', 'createSyncAccessHandle()')}} method.
 
-The handle provides its own functionality and there are a few differences depending on whether a file or directory was selected (see the [interfaces](#interfaces) section for specific details). You then can access file data, or information (including children) of the directory selected.
+Each handle provides its own functionality and there are a few differences depending on which one you are using (see the [interfaces](#interfaces) section for specific details). You then can access file data, or information (including children) of the directory selected.
 
-There is also "save" functionality, using the {{domxref('FileSystemWritableFileStream')}} interface. Once the data you'd like to save is in a format of {{domxref('Blob')}}, {{jsxref("String")}} object, string literal or {{jsxref('ArrayBuffer', 'buffer')}}, you can open a stream and save the data to a file. This can be the existing file or a new file.
+There is also "save" functionality:
+
+- In the case of the asynchronous handles, use the {{domxref('FileSystemWritableFileStream')}} interface. Once the data you'd like to save is in a format of {{domxref('Blob')}}, {{jsxref("String")}} object, string literal or {{jsxref('ArrayBuffer', 'buffer')}}, you can open a stream and save the data to a file. This can be the existing file or a new file.
+- In the case of the synchronous {{domxref('FileSystemSyncAccessHandle')}}, you write changes to a file using the {{domxref('FileSystemSyncAccessHandle.write', 'write()')}} method, then commit the changes to disk using {{domxref('FileSystemSyncAccessHandle.flush', 'flush()')}}.
 
 This API opens up potential functionality the web has been lacking. Still, security has been of utmost concern when designing the API, and access to file/directory data is disallowed unless the user specifically permits it.
 
@@ -46,6 +50,8 @@ This API opens up potential functionality the web has been lacking. Still, secur
   - : Provides a handle to a file system entry.
 - {{domxref("FileSystemDirectoryHandle")}}
   - : provides a handle to a file system directory.
+- {{domxref("FileSystemSyncAccessHandle")}}
+  - : Provides a synchronous handle to a file system entry. The synchronous nature of the file reads and writes allows for higher performance for critical methods in contexts where asynchronous operations come with high overhead, e.g., [WebAssembly](/en-US/docs/WebAssembly). This class is only accessible inside dedicated [Web Workers](/en-US/docs/Web/API/Web_Workers_API).
 - {{domxref("FileSystemWritableFileStream")}}
   - : is a {{domxref('WritableStream')}} object with additional convenience methods, which operates on a single file on disk.
 
@@ -175,6 +181,46 @@ writableStream.write({ type: "seek", position });
 writableStream.write({ type: "truncate", size });
 ```
 
+### Synchronously reading and writing a file
+
+The following asynchronous event handler function is contained inside a Web Worker. On receiving a message from the main thread it:
+
+- Creates a synchronous file access handle.
+- Gets the size of the file and creates an {{jsxref("ArrayBuffer")}} to contain it.
+- Reads the file contents into the buffer.
+- Encodes the message and writes it to the end of the file.
+- Persists the changes to disk and closes the 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();
+
+  // Get size of the file.
+  const fileSize = await accessHandle.getSize();
+  // Read file content to a buffer.
+  const buffer = new DataView(new ArrayBuffer(fileSize));
+  const readBuffer = accessHandle.read(buffer, { at: 0 });
+
+  // Write the message to the end of the file.
+  const encoder = new TextEncoder();
+  const encodedMessage = encoder.encode(message);
+  const writeBuffer = accessHandle.write(encodedMessage, { at: readBuffer });
+
+  // Persist changes to disk.
+  await accessHandle.flush();
+
+  // Always close FileSystemSyncAccessHandle if done.
+  await accessHandle.close();
+}
+```
+
 ## Specifications
 
 {{Specifications}}

files/en-us/web/api/filesystemfilehandle/createsyncaccesshandle/index.md

@@ -0,0 +1,85 @@
+---
+title: FileSystemFileHandle.createSyncAccessHandle()
+slug: Web/API/FileSystemFileHandle/createSyncAccessHandle
+page-type: web-api-instance-method
+tags:
+  - Directory
+  - File
+  - File System Access API
+  - FileSystemFileHandle
+  - Method
+  - createSyncAccessHandle
+  - working with files
+browser-compat: api.FileSystemFileHandle.createSyncAccessHandle
+---
+
+{{securecontext_header}}{{DefaultAPISidebar("File System Access API")}}
+
+The **`createSyncAccessHandle()`** method of the
+{{domxref("FileSystemFileHandle")}} interface returns a {{jsxref('Promise')}} which resolves to a {{domxref('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](/en-US/docs/Web/API/Web_Workers_API).
+
+Creating a {{domxref('FileSystemSyncAccessHandle')}} takes an exclusive lock on the file associated with the file handle. This prevents the creation of further {{domxref('FileSystemSyncAccessHandle')}}s or {{domxref('FileSystemWritableFileStream')}}s for the file, until the existing access handle is closed.
+
+If the file on disk changes or is removed after this method is called, the returned
+{{domxref('File')}} object will likely be no longer readable.
+
+## Syntax
+
+```js-nolint
+createSyncAccessHandle()
+```
+
+### Parameters
+
+None.
+
+### Return value
+
+A {{jsxref('Promise')}} which resolves to a {{domxref('FileSystemSyncAccessHandle')}} object.
+
+### Exceptions
+
+- `InvalidStateError` {{domxref("DOMException")}}
+  - : Thrown if the {{domxref('FileSystemSyncAccessHandle')}} object does not represent an file in the [origin private file system](https://fs.spec.whatwg.org/#origin-private-file-system).
+- `NoModificationAllowedError` {{domxref("DOMException")}}
+  - : Thrown if the browser is not able to take an exclusive lock on the file associated with the file handle.
+- `NotAllowedError` {{domxref("DOMException")}}
+  - : Thrown if the {{domxref('PermissionStatus.state')}} is not `granted` in
+    read mode.
+
+## 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.
+  await accessHandle.close();
+}
+```
+
+## Specifications
+
+{{Specifications}}
+
+## Browser compatibility
+
+{{Compat}}
+
+## See also
+
+- [File System Access API](/en-US/docs/Web/API/File_System_Access_API)
+- [The File System Access API: simplifying access to local files](https://web.dev/file-system-access/)

files/en-us/web/api/filesystemfilehandle/index.md

@@ -31,6 +31,10 @@ _Inherits methods from its parent, {{DOMxRef("FileSystemHandle")}}._
 - {{domxref('FileSystemFileHandle.getFile', 'getFile()')}}
   - : Returns a {{jsxref('Promise')}} which resolves to a {{domxref('File')}} object
     representing the state on disk of the entry represented by the handle.
+- {{domxref('FileSystemFileHandle.createSyncAccessHandle', 'createSyncAccessHandle()')}}
+  - : Returns a {{jsxref('Promise')}} which resolves to a {{domxref('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](/en-US/docs/Web/API/Web_Workers_API).
 - {{domxref('FileSystemFileHandle.createWritable', 'createWritable()')}}
   - : Returns a {{jsxref('Promise')}} which resolves to a newly created {{domxref('FileSystemWritableFileStream')}}
     object that can be used to write to a file.
@@ -81,6 +85,46 @@ async function writeFile(fileHandle, contents) {
 }
 ```
 
+### Synchronously reading and writing a file
+
+The following asynchronous event handler function is contained inside a Web Worker. On receiving a message from the main thread it:
+
+- Creates a synchronous file access handle.
+- Gets the size of the file and creates an {{jsxref("ArrayBuffer")}} to contain it.
+- Reads the file contents into the buffer.
+- Encodes the message and writes it to the end of the file.
+- Persists the changes to disk and closes the 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();
+
+  // Get size of the file.
+  const fileSize = await accessHandle.getSize();
+  // Read file content to a buffer.
+  const buffer = new DataView(new ArrayBuffer(fileSize));
+  const readBuffer = accessHandle.read(buffer, { at: 0 });
+
+  // Write the message to the end of the file.
+  const encoder = new TextEncoder();
+  const encodedMessage = encoder.encode(message);
+  const writeBuffer = accessHandle.write(encodedMessage, { at: readBuffer });
+
+  // Persist changes to disk.
+  await accessHandle.flush();
+
+  // Always close FileSystemSyncAccessHandle if done.
+  await accessHandle.close();
+}
+```
+
 ## Specifications
 
 {{Specifications}}

files/en-us/web/api/filesystemsyncaccesshandle/close/index.md

@@ -0,0 +1,97 @@
+---
+title: FileSystemSyncAccessHandle.close()
+slug: Web/API/FileSystemSyncAccessHandle/close
+page-type: web-api-instance-method
+tags:
+  - close
+  - Directory
+  - File
+  - File System Access API
+  - FileSystemSyncAccessHandle
+  - Method
+  - stream
+  - working with files
+browser-compat: api.FileSystemSyncAccessHandle.close
+---
+
+{{securecontext_header}}{{DefaultAPISidebar("File System Access API")}}
+
+The **`close()`** method of the
+{{domxref("FileSystemSyncAccessHandle")}} interface closes an open synchronous file handle, disabling any further operations on it and releasing the exclusive lock previously put on the file associated with the file handle.
+
+## Syntax
+
+```js-nolint
+close()
+```
+
+### Parameters
+
+None.
+
+### Return value
+
+A {{jsxref('Promise')}} which resolves to undefined.
+
+### Exceptions
+
+None.
+
+## Examples
+
+The following asynchronous event handler function is contained inside a Web Worker. On receiving a message from the main thread it:
+
+- Creates a synchronous file access handle.
+- Gets the size of the file and creates an {{jsxref("ArrayBuffer")}} to contain it.
+- Reads the file contents into the buffer.
+- Encodes the message and writes it to the end of the file.
+- Persists the changes to disk and closes the 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();
+
+  // Get size of the file.
+  const fileSize = await accessHandle.getSize();
+  // Read file content to a buffer.
+  const buffer = new DataView(new ArrayBuffer(fileSize));
+  const readBuffer = accessHandle.read(buffer, { at: 0 });
+
+  // Write the message to the end of the file.
+  const encoder = new TextEncoder();
+  const encodedMessage = encoder.encode(message);
+  const writeBuffer = accessHandle.write(encodedMessage, { at: readBuffer });
+
+  // Persist changes to disk.
+  await accessHandle.flush();
+
+  // Always close FileSystemSyncAccessHandle if done.
+  await accessHandle.close();
+}
+```
+
+Note that some browsers feature an experimental synchronous version of `close()` that provides further improved performance:
+
+```js
+accessHandle.close();
+```
+
+## Specifications
+
+{{Specifications}}
+
+## Browser compatibility
+
+{{Compat}}
+
+## See also
+
+- [File System Access API](/en-US/docs/Web/API/File_System_Access_API)
+- [The File System Access API: simplifying access to local files](https://web.dev/file-system-access/)