add content for FileSystemSyncAccessHandle

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

@@ -15,9 +15,6 @@ tags:
 browser-compat:
   - api.FileSystemHandle
   - api.FileSystemFileHandle
-  - api.FileSystemDirectoryHandle
-  - api.FileSystemWritableFileStream
-  - api.Window.showOpenFilePicker
 ---
 
 {{securecontext_header}}{{DefaultAPISidebar("File System Access API")}}
@@ -30,14 +27,23 @@ This API allows interaction with files on a user's local device, or on a user-ac
 
 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.
 
-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')}}.
 
-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.
+The interface {{domxref('FileSystemSyncAccessHandle')}} is also available to define a high-performance handle for _synchronous_ read/write operations (the other handle types are asynchronous). 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)). Note that it is only usable inside dedicated [Web Workers](/en-US/docs/Web/API/Web_Workers_API), for files within the [origin private file system](https://fs.spec.whatwg.org/#origin-private-file-system). {{domxref('FileSystemSyncAccessHandle')}} is accessed via the {{domxref('FileSystemFileHandle.createSyncAccessHandle', 'createSyncAccessHandle()')}} method.
 
-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.
+> **Note:** Writes performed using {{domxref('FileSystemSyncAccessHandle.write()')}} are in-place, meaning that changes are written to the actual underlying file at the same time as they are written to the writer. This is not the case with other writing mechanisms available in this API (e.g. {{domxref('FileSystemFileHandle.createWritable()')}}), where changes are not committed to disk until the writing stream is closed.
+
+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:
+
+- 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. You can optionally also call {{domxref('FileSystemSyncAccessHandle.flush', 'flush()')}} if you need the changes committed to disk at a specific time (otherwise you can leave the underlying operating system to handle this when it sees fit, which should be OK in most cases).
 
 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.
 
+> **Note:** The different exceptions that can be thrown when using the features of this API are listed on relevant pages as defined in the spec. However, the situation is made more complex by the interaction of the API and the underlying operating system. A proposal has been made to [list the error mappings in the spec](https://github.com/whatwg/fs/issues/57), which includes useful related information.
+
 ## Interfaces
 
 - {{domxref("FileSystemHandle")}}
@@ -46,6 +52,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, which operates in-place on a single file on disk. 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) for files within the [origin private file system](https://fs.spec.whatwg.org/#origin-private-file-system).
 - {{domxref("FileSystemWritableFileStream")}}
   - : is a {{domxref('WritableStream')}} object with additional convenience methods, which operates on a single file on disk.
 
@@ -175,6 +183,48 @@ 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 = 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.
+  accessHandle.flush();
+
+  // Always close FileSystemSyncAccessHandle if done.
+  accessHandle.close();
+}
+```
+
+> **Note:** In earlier versions of the spec, {{domxref("FileSystemSyncAccessHandle.close()", "close()")}}, {{domxref("FileSystemSyncAccessHandle.flush()", "flush()")}}, {{domxref("FileSystemSyncAccessHandle.getSize()", "getSize()")}}, and {{domxref("FileSystemSyncAccessHandle.truncate()", "truncate()")}} were wrongly specified as asynchronous methods. This has now been [amended](https://github.com/whatwg/fs/issues/7), but some browsers still support the asynchronous versions.
+
 ## Specifications
 
 {{Specifications}}

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

@@ -0,0 +1,81 @@
+---
+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}}{{APIRef("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) for files within the [origin private file system](https://fs.spec.whatwg.org/#origin-private-file-system).
+
+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.
+
+## 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 a 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 acquire a lock on the file associated with the file handle.
+- `NotAllowedError` {{domxref("DOMException")}}
+  - : Thrown if the permission has not been granted at the API level (i.e. {{domxref("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
+
+{{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/createwritable/index.md

@@ -13,7 +13,7 @@ tags:
 browser-compat: api.FileSystemFileHandle.createWritable
 ---
 
-{{securecontext_header}}{{DefaultAPISidebar("File System Access API")}}
+{{securecontext_header}}{{APIRef("File System Access API")}}
 
 The **`createWritable()`** method of the
 {{domxref("FileSystemFileHandle")}} interface creates

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

@@ -13,7 +13,7 @@ tags:
 browser-compat: api.FileSystemFileHandle.getFile
 ---
 
-{{securecontext_header}}{{DefaultAPISidebar("File System Access API")}}
+{{securecontext_header}}{{APIRef("File System Access API")}}
 
 The **`getFile()`** method of the
 {{domxref("FileSystemFileHandle")}} interface returns a {{jsxref('Promise')}} which resolves to a

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

@@ -12,9 +12,9 @@ tags:
 browser-compat: api.FileSystemFileHandle
 ---
 
-{{securecontext_header}}{{DefaultAPISidebar("File System Access API")}}
+{{securecontext_header}}{{APIRef("File System Access API")}}
 
-The **`FileSystemFileHandle`** interface of the {{domxref('File System Access API')}} represents a handle to a file system entry. The interface is accessed through the {{domxref('window.showOpenFilePicker()')}} method.
+The **`FileSystemFileHandle`** interface of the {{domxref("File System Access API", "File System Access API", "", "nocode")}} represents a handle to a file system entry. The interface is accessed through the {{domxref('window.showOpenFilePicker()')}} method.
 
 Note that read and write operations depend on file-access permissions that do not persist after a page refresh if no other tabs for that origin remain open. The {{domxref("FileSystemHandle.queryPermission()", "queryPermission")}} method of the {{domxref("FileSystemHandle")}} interface can be used to verify permission state before accessing a file.
 
@@ -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,48 @@ 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 = 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.
+  accessHandle.flush();
+
+  // Always close FileSystemSyncAccessHandle if done.
+  accessHandle.close();
+}
+```
+
+> **Note:** In earlier versions of the spec, {{domxref("FileSystemSyncAccessHandle.close()", "close()")}}, {{domxref("FileSystemSyncAccessHandle.flush()", "flush()")}}, {{domxref("FileSystemSyncAccessHandle.getSize()", "getSize()")}}, and {{domxref("FileSystemSyncAccessHandle.truncate()", "truncate()")}} were wrongly specified as asynchronous methods. This has now been [amended](https://github.com/whatwg/fs/issues/7), but some browsers still support the asynchronous versions.
+
 ## Specifications
 
 {{Specifications}}

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

@@ -0,0 +1,93 @@
+---
+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}}{{APIRef("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 = 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.
+  accessHandle.flush();
+
+  // Always close FileSystemSyncAccessHandle if done.
+  accessHandle.close();
+}
+```
+
+> **Note:** In earlier versions of the spec, `close()`, {{domxref("FileSystemSyncAccessHandle.flush()", "flush()")}}, {{domxref("FileSystemSyncAccessHandle.getSize()", "getSize()")}}, and {{domxref("FileSystemSyncAccessHandle.truncate()", "truncate()")}} were wrongly specified as asynchronous methods. This has now been [amended](https://github.com/whatwg/fs/issues/7), but some browsers still support the asynchronous versions.
+
+## 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/)