From 97fca2112a3c0d0fc45816b1f239c90c6da7b033 Mon Sep 17 00:00:00 2001 From: Chris Mills Date: Tue, 25 Oct 2022 10:08:47 +0100 Subject: [PATCH 01/19] add content for FileSystemSyncAccessHandle --- .../web/api/file_system_access_api/index.md | 54 +++++++++- .../createsyncaccesshandle/index.md | 85 +++++++++++++++ .../web/api/filesystemfilehandle/index.md | 44 ++++++++ .../filesystemsyncaccesshandle/close/index.md | 97 +++++++++++++++++ .../filesystemsyncaccesshandle/flush/index.md | 97 +++++++++++++++++ .../getsize/index.md | 98 +++++++++++++++++ .../api/filesystemsyncaccesshandle/index.md | 102 ++++++++++++++++++ .../filesystemsyncaccesshandle/read/index.md | 98 +++++++++++++++++ .../truncate/index.md | 82 ++++++++++++++ .../filesystemsyncaccesshandle/write/index.md | 98 +++++++++++++++++ files/jsondata/GroupData.json | 1 + 11 files changed, 852 insertions(+), 4 deletions(-) create mode 100644 files/en-us/web/api/filesystemfilehandle/createsyncaccesshandle/index.md create mode 100644 files/en-us/web/api/filesystemsyncaccesshandle/close/index.md create mode 100644 files/en-us/web/api/filesystemsyncaccesshandle/flush/index.md create mode 100644 files/en-us/web/api/filesystemsyncaccesshandle/getsize/index.md create mode 100644 files/en-us/web/api/filesystemsyncaccesshandle/index.md create mode 100644 files/en-us/web/api/filesystemsyncaccesshandle/read/index.md create mode 100644 files/en-us/web/api/filesystemsyncaccesshandle/truncate/index.md create mode 100644 files/en-us/web/api/filesystemsyncaccesshandle/write/index.md diff --git a/files/en-us/web/api/file_system_access_api/index.md b/files/en-us/web/api/file_system_access_api/index.md index 040c5f42a50c336..83ff8aea7323e98 100644 --- a/files/en-us/web/api/file_system_access_api/index.md +++ b/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 commit the changes to disk using the {{domxref('FileSystemSyncAccessHandle.flush', 'flush()')}} method. 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 draftFile = await root.getFileHandle('draft.txt'); + // Get sync access handle + const accessHandle = await draftFile.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}} diff --git a/files/en-us/web/api/filesystemfilehandle/createsyncaccesshandle/index.md b/files/en-us/web/api/filesystemfilehandle/createsyncaccesshandle/index.md new file mode 100644 index 000000000000000..75aafcbd2eacf20 --- /dev/null +++ b/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 draftFile = await root.getFileHandle('draft.txt'); + // Get sync access handle + const accessHandle = await draftFile.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/) diff --git a/files/en-us/web/api/filesystemfilehandle/index.md b/files/en-us/web/api/filesystemfilehandle/index.md index 17f76c01b2d5d5f..02e66a5ee30aa4e 100644 --- a/files/en-us/web/api/filesystemfilehandle/index.md +++ b/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 draftFile = await root.getFileHandle('draft.txt'); + // Get sync access handle + const accessHandle = await draftFile.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}} diff --git a/files/en-us/web/api/filesystemsyncaccesshandle/close/index.md b/files/en-us/web/api/filesystemsyncaccesshandle/close/index.md new file mode 100644 index 000000000000000..beb5d14602450c9 --- /dev/null +++ b/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 draftFile = await root.getFileHandle('draft.txt'); + // Get sync access handle + const accessHandle = await draftFile.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/) diff --git a/files/en-us/web/api/filesystemsyncaccesshandle/flush/index.md b/files/en-us/web/api/filesystemsyncaccesshandle/flush/index.md new file mode 100644 index 000000000000000..f1b4facf77f9f6b --- /dev/null +++ b/files/en-us/web/api/filesystemsyncaccesshandle/flush/index.md @@ -0,0 +1,97 @@ +--- +title: FileSystemSyncAccessHandle.flush() +slug: Web/API/FileSystemSyncAccessHandle/flush +page-type: web-api-instance-method +tags: + - flush + - Directory + - File + - File System Access API + - FileSystemSyncAccessHandle + - Method + - stream + - working with files +browser-compat: api.FileSystemSyncAccessHandle.flush +--- + +{{securecontext_header}}{{DefaultAPISidebar("File System Access API")}} + +The **`flush()`** method of the +{{domxref("FileSystemSyncAccessHandle")}} interface persists any changes made to the file associated with the handle via the {{domxref('FileSystemSyncAccessHandle.write', 'write()')}} method to disk. + +## Syntax + +```js-nolint +flush() +``` + +### 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 draftFile = await root.getFileHandle('draft.txt'); + // Get sync access handle + const accessHandle = await draftFile.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 `flush()` that provides further improved performance: + +```js +accessHandle.flush(); +``` + +## 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/) diff --git a/files/en-us/web/api/filesystemsyncaccesshandle/getsize/index.md b/files/en-us/web/api/filesystemsyncaccesshandle/getsize/index.md new file mode 100644 index 000000000000000..1b3e9ce4beb7b87 --- /dev/null +++ b/files/en-us/web/api/filesystemsyncaccesshandle/getsize/index.md @@ -0,0 +1,98 @@ +--- +title: FileSystemSyncAccessHandle.getSize() +slug: Web/API/FileSystemSyncAccessHandle/getSize +page-type: web-api-instance-method +tags: + - getSize + - Directory + - File + - File System Access API + - FileSystemSyncAccessHandle + - Method + - stream + - working with files +browser-compat: api.FileSystemSyncAccessHandle.getSize +--- + +{{securecontext_header}}{{DefaultAPISidebar("File System Access API")}} + +The **`getSize()`** method of the +{{domxref("FileSystemSyncAccessHandle")}} interface returns the size of the file associated with the handle in bytes. + +## Syntax + +```js-nolint +getSize() +``` + +### Parameters + +None. + +### Return value + +A {{jsxref('Promise')}} which resolves to a number representing the number of bytes in the file. + +### Exceptions + +- `InvalidStateError` {{domxref("DOMException")}} + - : Thrown if the associated access handle is already closed. + +## 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 draftFile = await root.getFileHandle('draft.txt'); + // Get sync access handle + const accessHandle = await draftFile.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 `getSize()` that provides further improved performance: + +```js +const fileSize = accessHandle.getSize(); +``` + +## 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/) diff --git a/files/en-us/web/api/filesystemsyncaccesshandle/index.md b/files/en-us/web/api/filesystemsyncaccesshandle/index.md new file mode 100644 index 000000000000000..b3252cdf09ba810 --- /dev/null +++ b/files/en-us/web/api/filesystemsyncaccesshandle/index.md @@ -0,0 +1,102 @@ +--- +title: FileSystemSyncAccessHandle +slug: Web/API/FileSystemSyncAccessHandle +page-type: web-api-interface +tags: + - Directory + - File + - File System Access API + - FileSystemSyncAccessHandle + - Interface + - working with files +browser-compat: api.FileSystemSyncAccessHandle +--- + +{{securecontext_header}}{{DefaultAPISidebar("File System Access API")}} + +The **`FileSystemSyncAccessHandle`** interface of the {{domxref('File System Access API')}} represents 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). + +The interface is accessed through the {{domxref('FileSystemFileHandle.createSyncAccessHandle()')}} method. + +{{InheritanceDiagram}} + +## Instance properties + +None. + +## Instance methods + +- {{domxref('FileSystemSyncAccessHandle.close', 'close()')}} + - : 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. +- {{domxref('FileSystemSyncAccessHandle.flush', 'flush()')}} + - : Persists any changes made to the file associated with the handle via the {{domxref('FileSystemSyncAccessHandle.write', 'write()')}} method to disk. +- {{domxref('FileSystemSyncAccessHandle.getSize', 'getSize()')}} + - : Returns the size of the file associated with the handle in bytes. +- {{domxref('FileSystemSyncAccessHandle.read', 'read()')}} + - : Reads the content of the file associated with the handle into a specified buffer, optionally at a given offset. +- {{domxref('FileSystemSyncAccessHandle.truncate', 'truncate()')}} + - : Resizes the file associated with the handle to a specified number of bytes. +- {{domxref('FileSystemSyncAccessHandle.write', 'write()')}} + - : Writes the content of a specified buffer to the file associated with the handle, optionally at a given offset. + +## 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 draftFile = await root.getFileHandle('draft.txt'); + // Get sync access handle + const accessHandle = await draftFile.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 experimental synchronous versions of the {{domxref('FileSystemSyncAccessHandle.close', 'close()')}}, {{domxref('FileSystemSyncAccessHandle.flush', 'flush()')}}, {{domxref('FileSystemSyncAccessHandle.getSize', 'getSize()')}}, and {{domxref('FileSystemSyncAccessHandle.truncate', 'truncate()')}} methods that provide further improved performance: + +```js +accessHandle.close(); +accessHandle.flush(); +const fileSize = accessHandle.getSize(); +accessHandle.truncate(0); +``` + +## 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/) diff --git a/files/en-us/web/api/filesystemsyncaccesshandle/read/index.md b/files/en-us/web/api/filesystemsyncaccesshandle/read/index.md new file mode 100644 index 000000000000000..ce81d52197df3d5 --- /dev/null +++ b/files/en-us/web/api/filesystemsyncaccesshandle/read/index.md @@ -0,0 +1,98 @@ +--- +title: FileSystemSyncAccessHandle.read() +slug: Web/API/FileSystemSyncAccessHandle/read +page-type: web-api-instance-method +tags: + - read + - Directory + - File + - File System Access API + - FileSystemSyncAccessHandle + - Method + - stream + - working with files +browser-compat: api.FileSystemSyncAccessHandle.read +--- + +{{securecontext_header}}{{DefaultAPISidebar("File System Access API")}} + +The **`read()`** method of the +{{domxref("FileSystemSyncAccessHandle")}} interface reads the content of the file associated with the handle into a specified buffer, optionally at a given offset. + +## Syntax + +```js-nolint +read(buffer, FileSystemReadWriteOptions) +``` + +### Parameters + +- `buffer` + - : An {{jsxref("ArrayBuffer")}} or `ArrayBufferView` (such as a {{jsxref("DataView")}}) representing the buffer that the file content should be read into. +- `FileSystemReadWriteOptions` {{optional_inline}} + - : An options object containing the following properties + + - `at` + - : A number representing the offset in bytes that the file should be read from. + +### Return value + +A {{jsxref('Promise')}} which resolves to a number representing the number of bytes read from the file. + +### Exceptions + +- `InvalidStateError` {{domxref("DOMException")}} + - : Thrown if the associated access handle is already closed. + +## 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 draftFile = await root.getFileHandle('draft.txt'); + // Get sync access handle + const accessHandle = await draftFile.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}} + +## 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/) diff --git a/files/en-us/web/api/filesystemsyncaccesshandle/truncate/index.md b/files/en-us/web/api/filesystemsyncaccesshandle/truncate/index.md new file mode 100644 index 000000000000000..51e66c40ba03090 --- /dev/null +++ b/files/en-us/web/api/filesystemsyncaccesshandle/truncate/index.md @@ -0,0 +1,82 @@ +--- +title: FileSystemSyncAccessHandle.truncate() +slug: Web/API/FileSystemSyncAccessHandle/truncate +page-type: web-api-instance-method +tags: + - truncate + - Directory + - File + - File System Access API + - FileSystemSyncAccessHandle + - Method + - stream + - working with files +browser-compat: api.FileSystemSyncAccessHandle.truncate +--- + +{{securecontext_header}}{{DefaultAPISidebar("File System Access API")}} + +The **`truncate()`** method of the +{{domxref("FileSystemSyncAccessHandle")}} interface resizes the file associated with the handle to a specified number of bytes. + +## Syntax + +```js-nolint +truncate(newSize) +``` + +### Parameters + +- `newSize` + - : The number of bytes to resize the file to. + +### Return value + +A {{jsxref('Promise')}} which resolves to undefined. + +### Exceptions + +- `InvalidStateError` {{domxref("DOMException")}} + - : Thrown if the associated access handle is already closed, or if the modification of the file's binary data otherwise fails. +- `QuotaExceededError` {{domxref("DOMException")}} + - : Thrown if the `newSize` is larger than the original size of the file, and exceeds the browser's [storage quota](/en-US/docs/Web/API/IndexedDB_API/Browser_storage_limits_and_eviction_criteria). + +## Examples + +```js +async function truncateFile() { + // Get handle to draft file + const root = await navigator.storage.getDirectory(); + const draftFile = await root.getFileHandle('draft.txt'); + // Get sync access handle + const accessHandle = await draftFile.createSyncAccessHandle(); + + // Truncate the file to 0 bytes + await accessHandle.truncate(0); + + // 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 `truncate()` that provides further improved performance: + +```js +accessHandle.truncate(0); +``` + +## 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/) diff --git a/files/en-us/web/api/filesystemsyncaccesshandle/write/index.md b/files/en-us/web/api/filesystemsyncaccesshandle/write/index.md new file mode 100644 index 000000000000000..53732fc89cde289 --- /dev/null +++ b/files/en-us/web/api/filesystemsyncaccesshandle/write/index.md @@ -0,0 +1,98 @@ +--- +title: FileSystemSyncAccessHandle.write() +slug: Web/API/FileSystemSyncAccessHandle/write +page-type: web-api-instance-method +tags: + - write + - Directory + - File + - File System Access API + - FileSystemSyncAccessHandle + - Method + - stream + - working with files +browser-compat: api.FileSystemSyncAccessHandle.write +--- + +{{securecontext_header}}{{DefaultAPISidebar("File System Access API")}} + +The **`write()`** method of the +{{domxref("FileSystemSyncAccessHandle")}} interface writes the content of a specified buffer to the file associated with the handle, optionally at a given offset. + +## Syntax + +```js-nolint +write(buffer, FileSystemReadWriteOptions) +``` + +### Parameters + +- `buffer` + - : An {{jsxref("ArrayBuffer")}} or `ArrayBufferView` (such as a {{jsxref("DataView")}}) representing the buffer to be written to the file. +- `FileSystemReadWriteOptions` {{optional_inline}} + - : An options object containing the following properties: + + - `at` + - : A number representing the offset in bytes from the start of the file that the buffer should be written at. + +### Return value + +A {{jsxref('Promise')}} which resolves to a number representing the number of bytes written to the file. + +### Exceptions + +- `InvalidStateError` {{domxref("DOMException")}} + - : Thrown if the associated access handle is already closed. + +## 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 draftFile = await root.getFileHandle('draft.txt'); + // Get sync access handle + const accessHandle = await draftFile.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}} + +## 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/) diff --git a/files/jsondata/GroupData.json b/files/jsondata/GroupData.json index 01cd81977eb8545..7d8074636439fa2 100644 --- a/files/jsondata/GroupData.json +++ b/files/jsondata/GroupData.json @@ -450,6 +450,7 @@ "FileSystemHandle", "FileSystemFileHandle", "FileSystemDirectoryHandle", + "FileSystemSyncAccessHandle", "FileSystemWritableFileStream" ], "methods": [ From 13b8e5eafd47ef12c9c940ad0cc482a23a06fb82 Mon Sep 17 00:00:00 2001 From: Chris Mills Date: Wed, 26 Oct 2022 07:19:31 +0100 Subject: [PATCH 02/19] Update files/en-us/web/api/file_system_access_api/index.md Co-authored-by: Thomas Steiner --- files/en-us/web/api/file_system_access_api/index.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/files/en-us/web/api/file_system_access_api/index.md b/files/en-us/web/api/file_system_access_api/index.md index 83ff8aea7323e98..650f4e75cb32ad8 100644 --- a/files/en-us/web/api/file_system_access_api/index.md +++ b/files/en-us/web/api/file_system_access_api/index.md @@ -198,9 +198,9 @@ onmessage = async (e) => { // Get handle to draft file const root = await navigator.storage.getDirectory(); - const draftFile = await root.getFileHandle('draft.txt'); + const draftHandle = await root.getFileHandle('draft.txt', { create: true }); // Get sync access handle - const accessHandle = await draftFile.createSyncAccessHandle(); + const accessHandle = await draftHandle.createSyncAccessHandle(); // Get size of the file. const fileSize = await accessHandle.getSize(); From 1e5a8337645836137c8007a839d6ceb07cd63506 Mon Sep 17 00:00:00 2001 From: Chris Mills Date: Wed, 26 Oct 2022 07:22:12 +0100 Subject: [PATCH 03/19] Update files/en-us/web/api/file_system_access_api/index.md Co-authored-by: Thomas Steiner --- files/en-us/web/api/file_system_access_api/index.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/files/en-us/web/api/file_system_access_api/index.md b/files/en-us/web/api/file_system_access_api/index.md index 650f4e75cb32ad8..c074a0171038c9a 100644 --- a/files/en-us/web/api/file_system_access_api/index.md +++ b/files/en-us/web/api/file_system_access_api/index.md @@ -211,7 +211,7 @@ onmessage = async (e) => { // 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 }); + const writeBuffer = accessHandle.write(encodedMessage, { at: readBuffer }); // Persist changes to disk. await accessHandle.flush(); From 97e4ae446f2b72af7e3e562515ef0284b504d076 Mon Sep 17 00:00:00 2001 From: Chris Mills Date: Wed, 26 Oct 2022 07:24:05 +0100 Subject: [PATCH 04/19] Update files/en-us/web/api/file_system_access_api/index.md Co-authored-by: Thomas Steiner --- files/en-us/web/api/file_system_access_api/index.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/files/en-us/web/api/file_system_access_api/index.md b/files/en-us/web/api/file_system_access_api/index.md index c074a0171038c9a..2ca75e1d27ef492 100644 --- a/files/en-us/web/api/file_system_access_api/index.md +++ b/files/en-us/web/api/file_system_access_api/index.md @@ -206,7 +206,7 @@ onmessage = async (e) => { 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 }); + const readBuffer = accessHandle.read(buffer, { at: 0 }); // Write the message to the end of the file. const encoder = new TextEncoder(); From 161b3d647988f80908c7920d859c43eec77adba5 Mon Sep 17 00:00:00 2001 From: Chris Mills Date: Wed, 26 Oct 2022 07:28:25 +0100 Subject: [PATCH 05/19] Making fix according to tomayac comment --- files/en-us/web/api/file_system_access_api/index.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/files/en-us/web/api/file_system_access_api/index.md b/files/en-us/web/api/file_system_access_api/index.md index 83ff8aea7323e98..134303ffc2e6bbd 100644 --- a/files/en-us/web/api/file_system_access_api/index.md +++ b/files/en-us/web/api/file_system_access_api/index.md @@ -38,7 +38,7 @@ Each handle provides its own functionality and there are a few differences depen 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 commit the changes to disk using the {{domxref('FileSystemSyncAccessHandle.flush', 'flush()')}} method. +- 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. From a52a0c6af286e94c012dbd36051f48e954ba4681 Mon Sep 17 00:00:00 2001 From: Chris Mills Date: Wed, 26 Oct 2022 07:38:37 +0100 Subject: [PATCH 06/19] fixing code examples according to tomayac comments --- .../filesystemfilehandle/createsyncaccesshandle/index.md | 4 ++-- files/en-us/web/api/filesystemfilehandle/index.md | 8 ++++---- .../web/api/filesystemsyncaccesshandle/close/index.md | 8 ++++---- .../web/api/filesystemsyncaccesshandle/flush/index.md | 8 ++++---- .../web/api/filesystemsyncaccesshandle/getsize/index.md | 8 ++++---- files/en-us/web/api/filesystemsyncaccesshandle/index.md | 8 ++++---- .../web/api/filesystemsyncaccesshandle/read/index.md | 8 ++++---- .../web/api/filesystemsyncaccesshandle/truncate/index.md | 4 ++-- .../web/api/filesystemsyncaccesshandle/write/index.md | 8 ++++---- 9 files changed, 32 insertions(+), 32 deletions(-) diff --git a/files/en-us/web/api/filesystemfilehandle/createsyncaccesshandle/index.md b/files/en-us/web/api/filesystemfilehandle/createsyncaccesshandle/index.md index 75aafcbd2eacf20..fe467d5975acb41 100644 --- a/files/en-us/web/api/filesystemfilehandle/createsyncaccesshandle/index.md +++ b/files/en-us/web/api/filesystemfilehandle/createsyncaccesshandle/index.md @@ -60,9 +60,9 @@ onmessage = async (e) => { // Get handle to draft file const root = await navigator.storage.getDirectory(); - const draftFile = await root.getFileHandle('draft.txt'); + const draftHandle = await root.getFileHandle('draft.txt', { create: true }); // Get sync access handle - const accessHandle = await draftFile.createSyncAccessHandle(); + const accessHandle = await draftHandle.createSyncAccessHandle(); ... diff --git a/files/en-us/web/api/filesystemfilehandle/index.md b/files/en-us/web/api/filesystemfilehandle/index.md index 02e66a5ee30aa4e..7dded5d14bf4c1a 100644 --- a/files/en-us/web/api/filesystemfilehandle/index.md +++ b/files/en-us/web/api/filesystemfilehandle/index.md @@ -102,20 +102,20 @@ onmessage = async (e) => { // Get handle to draft file const root = await navigator.storage.getDirectory(); - const draftFile = await root.getFileHandle('draft.txt'); + const draftHandle = await root.getFileHandle('draft.txt', { create: true }); // Get sync access handle - const accessHandle = await draftFile.createSyncAccessHandle(); + 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 }); + 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 }); + const writeBuffer = accessHandle.write(encodedMessage, { at: readBuffer }); // Persist changes to disk. await accessHandle.flush(); diff --git a/files/en-us/web/api/filesystemsyncaccesshandle/close/index.md b/files/en-us/web/api/filesystemsyncaccesshandle/close/index.md index beb5d14602450c9..db4f88dc8b55084 100644 --- a/files/en-us/web/api/filesystemsyncaccesshandle/close/index.md +++ b/files/en-us/web/api/filesystemsyncaccesshandle/close/index.md @@ -54,20 +54,20 @@ onmessage = async (e) => { // Get handle to draft file const root = await navigator.storage.getDirectory(); - const draftFile = await root.getFileHandle('draft.txt'); + const draftHandle = await root.getFileHandle('draft.txt', { create: true }); // Get sync access handle - const accessHandle = await draftFile.createSyncAccessHandle(); + 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 }); + 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 }); + const writeBuffer = accessHandle.write(encodedMessage, { at: readBuffer }); // Persist changes to disk. await accessHandle.flush(); diff --git a/files/en-us/web/api/filesystemsyncaccesshandle/flush/index.md b/files/en-us/web/api/filesystemsyncaccesshandle/flush/index.md index f1b4facf77f9f6b..5b1bbabe29fc548 100644 --- a/files/en-us/web/api/filesystemsyncaccesshandle/flush/index.md +++ b/files/en-us/web/api/filesystemsyncaccesshandle/flush/index.md @@ -54,20 +54,20 @@ onmessage = async (e) => { // Get handle to draft file const root = await navigator.storage.getDirectory(); - const draftFile = await root.getFileHandle('draft.txt'); + const draftHandle = await root.getFileHandle('draft.txt', { create: true }); // Get sync access handle - const accessHandle = await draftFile.createSyncAccessHandle(); + 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 }); + 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 }); + const writeBuffer = accessHandle.write(encodedMessage, { at: readBuffer }); // Persist changes to disk. await accessHandle.flush(); diff --git a/files/en-us/web/api/filesystemsyncaccesshandle/getsize/index.md b/files/en-us/web/api/filesystemsyncaccesshandle/getsize/index.md index 1b3e9ce4beb7b87..8914c89cf46724d 100644 --- a/files/en-us/web/api/filesystemsyncaccesshandle/getsize/index.md +++ b/files/en-us/web/api/filesystemsyncaccesshandle/getsize/index.md @@ -55,20 +55,20 @@ onmessage = async (e) => { // Get handle to draft file const root = await navigator.storage.getDirectory(); - const draftFile = await root.getFileHandle('draft.txt'); + const draftHandle = await root.getFileHandle('draft.txt', { create: true }); // Get sync access handle - const accessHandle = await draftFile.createSyncAccessHandle(); + 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 }); + 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 }); + const writeBuffer = accessHandle.write(encodedMessage, { at: readBuffer }); // Persist changes to disk. await accessHandle.flush(); diff --git a/files/en-us/web/api/filesystemsyncaccesshandle/index.md b/files/en-us/web/api/filesystemsyncaccesshandle/index.md index b3252cdf09ba810..acc30c0f64e2e9c 100644 --- a/files/en-us/web/api/filesystemsyncaccesshandle/index.md +++ b/files/en-us/web/api/filesystemsyncaccesshandle/index.md @@ -56,20 +56,20 @@ onmessage = async (e) => { // Get handle to draft file const root = await navigator.storage.getDirectory(); - const draftFile = await root.getFileHandle('draft.txt'); + const draftHandle = await root.getFileHandle('draft.txt', { create: true }); // Get sync access handle - const accessHandle = await draftFile.createSyncAccessHandle(); + 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 }); + 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 }); + const writeBuffer = accessHandle.write(encodedMessage, { at: readBuffer }); // Persist changes to disk. await accessHandle.flush(); diff --git a/files/en-us/web/api/filesystemsyncaccesshandle/read/index.md b/files/en-us/web/api/filesystemsyncaccesshandle/read/index.md index ce81d52197df3d5..7f4ae8236266b4c 100644 --- a/files/en-us/web/api/filesystemsyncaccesshandle/read/index.md +++ b/files/en-us/web/api/filesystemsyncaccesshandle/read/index.md @@ -61,20 +61,20 @@ onmessage = async (e) => { // Get handle to draft file const root = await navigator.storage.getDirectory(); - const draftFile = await root.getFileHandle('draft.txt'); + const draftHandle = await root.getFileHandle('draft.txt', { create: true }); // Get sync access handle - const accessHandle = await draftFile.createSyncAccessHandle(); + 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 }); + 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 }); + const writeBuffer = accessHandle.write(encodedMessage, { at: readBuffer }); // Persist changes to disk. await accessHandle.flush(); diff --git a/files/en-us/web/api/filesystemsyncaccesshandle/truncate/index.md b/files/en-us/web/api/filesystemsyncaccesshandle/truncate/index.md index 51e66c40ba03090..256a5a85576c268 100644 --- a/files/en-us/web/api/filesystemsyncaccesshandle/truncate/index.md +++ b/files/en-us/web/api/filesystemsyncaccesshandle/truncate/index.md @@ -47,9 +47,9 @@ A {{jsxref('Promise')}} which resolves to undefined. async function truncateFile() { // Get handle to draft file const root = await navigator.storage.getDirectory(); - const draftFile = await root.getFileHandle('draft.txt'); + const draftHandle = await root.getFileHandle('draft.txt', { create: true }); // Get sync access handle - const accessHandle = await draftFile.createSyncAccessHandle(); + const accessHandle = await draftHandle.createSyncAccessHandle(); // Truncate the file to 0 bytes await accessHandle.truncate(0); diff --git a/files/en-us/web/api/filesystemsyncaccesshandle/write/index.md b/files/en-us/web/api/filesystemsyncaccesshandle/write/index.md index 53732fc89cde289..f27c0608a96039d 100644 --- a/files/en-us/web/api/filesystemsyncaccesshandle/write/index.md +++ b/files/en-us/web/api/filesystemsyncaccesshandle/write/index.md @@ -61,20 +61,20 @@ onmessage = async (e) => { // Get handle to draft file const root = await navigator.storage.getDirectory(); - const draftFile = await root.getFileHandle('draft.txt'); + const draftHandle = await root.getFileHandle('draft.txt', { create: true }); // Get sync access handle - const accessHandle = await draftFile.createSyncAccessHandle(); + 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 }); + 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 }); + const writeBuffer = accessHandle.write(encodedMessage, { at: readBuffer }); // Persist changes to disk. await accessHandle.flush(); From 705ab9c854dd5ad3a103cf5d2b5f92b97625f720 Mon Sep 17 00:00:00 2001 From: Chris Mills Date: Wed, 26 Oct 2022 09:08:58 +0100 Subject: [PATCH 07/19] Update files/en-us/web/api/filesystemfilehandle/createsyncaccesshandle/index.md Co-authored-by: Jean-Yves Perrier --- .../api/filesystemfilehandle/createsyncaccesshandle/index.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/files/en-us/web/api/filesystemfilehandle/createsyncaccesshandle/index.md b/files/en-us/web/api/filesystemfilehandle/createsyncaccesshandle/index.md index fe467d5975acb41..6fba3ea717ae01f 100644 --- a/files/en-us/web/api/filesystemfilehandle/createsyncaccesshandle/index.md +++ b/files/en-us/web/api/filesystemfilehandle/createsyncaccesshandle/index.md @@ -55,7 +55,7 @@ The following asynchronous event handler function is contained inside a Web Work ```js onmessage = async (e) => { - // retrieve message sent to work from main script + // Retrieve message sent to work from main script const message = e.data; // Get handle to draft file From d2b8610a982c53667fcd080d9637351e94552409 Mon Sep 17 00:00:00 2001 From: Chris Mills Date: Wed, 26 Oct 2022 09:09:08 +0100 Subject: [PATCH 08/19] Update files/en-us/web/api/filesystemfilehandle/createsyncaccesshandle/index.md Co-authored-by: Jean-Yves Perrier --- .../api/filesystemfilehandle/createsyncaccesshandle/index.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/files/en-us/web/api/filesystemfilehandle/createsyncaccesshandle/index.md b/files/en-us/web/api/filesystemfilehandle/createsyncaccesshandle/index.md index 6fba3ea717ae01f..256bc995e11feb1 100644 --- a/files/en-us/web/api/filesystemfilehandle/createsyncaccesshandle/index.md +++ b/files/en-us/web/api/filesystemfilehandle/createsyncaccesshandle/index.md @@ -64,7 +64,7 @@ onmessage = async (e) => { // Get sync access handle const accessHandle = await draftHandle.createSyncAccessHandle(); - ... +// … // Always close FileSystemSyncAccessHandle if done. await accessHandle.close(); From 9ac69ce9a9450ce3b1609ca202d943ab23b86d76 Mon Sep 17 00:00:00 2001 From: Chris Mills Date: Wed, 26 Oct 2022 09:09:22 +0100 Subject: [PATCH 09/19] Update files/en-us/web/api/filesystemfilehandle/index.md Co-authored-by: Jean-Yves Perrier --- files/en-us/web/api/filesystemfilehandle/index.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/files/en-us/web/api/filesystemfilehandle/index.md b/files/en-us/web/api/filesystemfilehandle/index.md index 7dded5d14bf4c1a..448120202a39df8 100644 --- a/files/en-us/web/api/filesystemfilehandle/index.md +++ b/files/en-us/web/api/filesystemfilehandle/index.md @@ -97,7 +97,7 @@ The following asynchronous event handler function is contained inside a Web Work ```js onmessage = async (e) => { - // retrieve message sent to work from main script + // Retrieve message sent to work from main script const message = e.data; // Get handle to draft file From f9d12bf49bc5936dd7bf1a99cba4fbe10a6e6084 Mon Sep 17 00:00:00 2001 From: Chris Mills Date: Wed, 26 Oct 2022 09:09:34 +0100 Subject: [PATCH 10/19] Update files/en-us/web/api/filesystemsyncaccesshandle/close/index.md Co-authored-by: Jean-Yves Perrier --- files/en-us/web/api/filesystemsyncaccesshandle/close/index.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/files/en-us/web/api/filesystemsyncaccesshandle/close/index.md b/files/en-us/web/api/filesystemsyncaccesshandle/close/index.md index db4f88dc8b55084..ec4261bf11d5d21 100644 --- a/files/en-us/web/api/filesystemsyncaccesshandle/close/index.md +++ b/files/en-us/web/api/filesystemsyncaccesshandle/close/index.md @@ -49,7 +49,7 @@ The following asynchronous event handler function is contained inside a Web Work ```js onmessage = async (e) => { - // retrieve message sent to work from main script + // Retrieve message sent to work from main script const message = e.data; // Get handle to draft file From 5dd5ac6f2197b51a1acb4f76857fabc30b91bfb9 Mon Sep 17 00:00:00 2001 From: Chris Mills Date: Wed, 26 Oct 2022 09:09:44 +0100 Subject: [PATCH 11/19] Update files/en-us/web/api/filesystemsyncaccesshandle/flush/index.md Co-authored-by: Jean-Yves Perrier --- files/en-us/web/api/filesystemsyncaccesshandle/flush/index.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/files/en-us/web/api/filesystemsyncaccesshandle/flush/index.md b/files/en-us/web/api/filesystemsyncaccesshandle/flush/index.md index 5b1bbabe29fc548..ee03f17cb2092cf 100644 --- a/files/en-us/web/api/filesystemsyncaccesshandle/flush/index.md +++ b/files/en-us/web/api/filesystemsyncaccesshandle/flush/index.md @@ -49,7 +49,7 @@ The following asynchronous event handler function is contained inside a Web Work ```js onmessage = async (e) => { - // retrieve message sent to work from main script + // Retrieve message sent to work from main script const message = e.data; // Get handle to draft file From 514c0fdd57e4e80575b02254a14e2e8e4ad5f84c Mon Sep 17 00:00:00 2001 From: Chris Mills Date: Wed, 26 Oct 2022 09:09:55 +0100 Subject: [PATCH 12/19] Update files/en-us/web/api/filesystemsyncaccesshandle/getsize/index.md Co-authored-by: Jean-Yves Perrier --- files/en-us/web/api/filesystemsyncaccesshandle/getsize/index.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/files/en-us/web/api/filesystemsyncaccesshandle/getsize/index.md b/files/en-us/web/api/filesystemsyncaccesshandle/getsize/index.md index 8914c89cf46724d..004b0fe2a5aa968 100644 --- a/files/en-us/web/api/filesystemsyncaccesshandle/getsize/index.md +++ b/files/en-us/web/api/filesystemsyncaccesshandle/getsize/index.md @@ -50,7 +50,7 @@ The following asynchronous event handler function is contained inside a Web Work ```js onmessage = async (e) => { - // retrieve message sent to work from main script + // Retrieve message sent to work from main script const message = e.data; // Get handle to draft file From 16853368c554e0c085254baaf7a9b621c3bc9209 Mon Sep 17 00:00:00 2001 From: Chris Mills Date: Wed, 26 Oct 2022 09:10:10 +0100 Subject: [PATCH 13/19] Update files/en-us/web/api/filesystemsyncaccesshandle/index.md Co-authored-by: Jean-Yves Perrier --- files/en-us/web/api/filesystemsyncaccesshandle/index.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/files/en-us/web/api/filesystemsyncaccesshandle/index.md b/files/en-us/web/api/filesystemsyncaccesshandle/index.md index acc30c0f64e2e9c..7f16cd72fc9518e 100644 --- a/files/en-us/web/api/filesystemsyncaccesshandle/index.md +++ b/files/en-us/web/api/filesystemsyncaccesshandle/index.md @@ -51,7 +51,7 @@ The following asynchronous event handler function is contained inside a Web Work ```js onmessage = async (e) => { - // retrieve message sent to work from main script + // Retrieve message sent to work from main script const message = e.data; // Get handle to draft file From 8bdd5fa06246c1eb9d56bdbbcfe22c4d1f24f953 Mon Sep 17 00:00:00 2001 From: Chris Mills Date: Wed, 26 Oct 2022 09:10:23 +0100 Subject: [PATCH 14/19] Update files/en-us/web/api/filesystemsyncaccesshandle/read/index.md Co-authored-by: Jean-Yves Perrier --- files/en-us/web/api/filesystemsyncaccesshandle/read/index.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/files/en-us/web/api/filesystemsyncaccesshandle/read/index.md b/files/en-us/web/api/filesystemsyncaccesshandle/read/index.md index 7f4ae8236266b4c..998f523b5324be0 100644 --- a/files/en-us/web/api/filesystemsyncaccesshandle/read/index.md +++ b/files/en-us/web/api/filesystemsyncaccesshandle/read/index.md @@ -30,7 +30,7 @@ read(buffer, FileSystemReadWriteOptions) - `buffer` - : An {{jsxref("ArrayBuffer")}} or `ArrayBufferView` (such as a {{jsxref("DataView")}}) representing the buffer that the file content should be read into. - `FileSystemReadWriteOptions` {{optional_inline}} - - : An options object containing the following properties + - : An options object containing the following properties: - `at` - : A number representing the offset in bytes that the file should be read from. From b9b16df22b8b02ff792fddd2d5e59839f7c49122 Mon Sep 17 00:00:00 2001 From: Chris Mills Date: Wed, 26 Oct 2022 09:10:37 +0100 Subject: [PATCH 15/19] Update files/en-us/web/api/filesystemsyncaccesshandle/read/index.md Co-authored-by: Jean-Yves Perrier --- files/en-us/web/api/filesystemsyncaccesshandle/read/index.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/files/en-us/web/api/filesystemsyncaccesshandle/read/index.md b/files/en-us/web/api/filesystemsyncaccesshandle/read/index.md index 998f523b5324be0..fcb0efc8af1e0dd 100644 --- a/files/en-us/web/api/filesystemsyncaccesshandle/read/index.md +++ b/files/en-us/web/api/filesystemsyncaccesshandle/read/index.md @@ -56,7 +56,7 @@ The following asynchronous event handler function is contained inside a Web Work ```js onmessage = async (e) => { - // retrieve message sent to work from main script + // Retrieve message sent to work from main script const message = e.data; // Get handle to draft file From 6c518da3e92b3004526c195081e9f45dc3e8938d Mon Sep 17 00:00:00 2001 From: Chris Mills Date: Wed, 26 Oct 2022 09:10:50 +0100 Subject: [PATCH 16/19] Update files/en-us/web/api/filesystemsyncaccesshandle/write/index.md Co-authored-by: Jean-Yves Perrier --- files/en-us/web/api/filesystemsyncaccesshandle/write/index.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/files/en-us/web/api/filesystemsyncaccesshandle/write/index.md b/files/en-us/web/api/filesystemsyncaccesshandle/write/index.md index f27c0608a96039d..bcd2702e80235b9 100644 --- a/files/en-us/web/api/filesystemsyncaccesshandle/write/index.md +++ b/files/en-us/web/api/filesystemsyncaccesshandle/write/index.md @@ -56,7 +56,7 @@ The following asynchronous event handler function is contained inside a Web Work ```js onmessage = async (e) => { - // retrieve message sent to work from main script + // Retrieve message sent to work from main script const message = e.data; // Get handle to draft file From 45515477e6bc15fcb4376e21d151e692998a6fd0 Mon Sep 17 00:00:00 2001 From: Chris Mills Date: Fri, 18 Nov 2022 09:32:32 +0000 Subject: [PATCH 17/19] Respond to a-sully review comments and make some other fixes --- .../web/api/file_system_access_api/index.md | 8 ++++--- .../createsyncaccesshandle/index.md | 16 ++++++-------- .../createwritable/index.md | 2 +- .../api/filesystemfilehandle/getfile/index.md | 2 +- .../web/api/filesystemfilehandle/index.md | 10 ++++----- .../filesystemsyncaccesshandle/close/index.md | 14 +++++-------- .../filesystemsyncaccesshandle/flush/index.md | 14 +++++-------- .../getsize/index.md | 14 +++++-------- .../api/filesystemsyncaccesshandle/index.md | 21 +++++++------------ .../filesystemsyncaccesshandle/read/index.md | 10 +++++---- .../truncate/index.md | 14 +++++-------- .../filesystemsyncaccesshandle/write/index.md | 10 +++++---- 12 files changed, 58 insertions(+), 77 deletions(-) diff --git a/files/en-us/web/api/file_system_access_api/index.md b/files/en-us/web/api/file_system_access_api/index.md index 8e971e50c3d9529..fb8fba61167c9f8 100644 --- a/files/en-us/web/api/file_system_access_api/index.md +++ b/files/en-us/web/api/file_system_access_api/index.md @@ -29,9 +29,11 @@ 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. 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). +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. -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 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')}}. + +{{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. 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. @@ -51,7 +53,7 @@ This API opens up potential functionality the web has been lacking. Still, secur - {{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). + - : 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) 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. diff --git a/files/en-us/web/api/filesystemfilehandle/createsyncaccesshandle/index.md b/files/en-us/web/api/filesystemfilehandle/createsyncaccesshandle/index.md index 256bc995e11feb1..f9849050485a242 100644 --- a/files/en-us/web/api/filesystemfilehandle/createsyncaccesshandle/index.md +++ b/files/en-us/web/api/filesystemfilehandle/createsyncaccesshandle/index.md @@ -13,17 +13,14 @@ tags: browser-compat: api.FileSystemFileHandle.createSyncAccessHandle --- -{{securecontext_header}}{{DefaultAPISidebar("File System Access API")}} +{{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). +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. - -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. +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 @@ -42,12 +39,11 @@ A {{jsxref('Promise')}} which resolves to a {{domxref('FileSystemSyncAccessHandl ### 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). + - : 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 take an exclusive lock on the file associated with the file handle. + - : 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 {{domxref('PermissionStatus.state')}} is not `granted` in - read mode. + - : Thrown if the permission has not been granted at the API level (i.e. {{domxref("FileSystemHandle.requestPermission")}} is required). ## Examples diff --git a/files/en-us/web/api/filesystemfilehandle/createwritable/index.md b/files/en-us/web/api/filesystemfilehandle/createwritable/index.md index 8e74d22079a2fa0..ef04f4c99a4240c 100644 --- a/files/en-us/web/api/filesystemfilehandle/createwritable/index.md +++ b/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 diff --git a/files/en-us/web/api/filesystemfilehandle/getfile/index.md b/files/en-us/web/api/filesystemfilehandle/getfile/index.md index 9c0d4e62aa083de..e3b5211d46b2373 100644 --- a/files/en-us/web/api/filesystemfilehandle/getfile/index.md +++ b/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 diff --git a/files/en-us/web/api/filesystemfilehandle/index.md b/files/en-us/web/api/filesystemfilehandle/index.md index 448120202a39df8..3a5037968117890 100644 --- a/files/en-us/web/api/filesystemfilehandle/index.md +++ b/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. @@ -107,7 +107,7 @@ onmessage = async (e) => { const accessHandle = await draftHandle.createSyncAccessHandle(); // Get size of the file. - const fileSize = await accessHandle.getSize(); + const fileSize = accessHandle.getSize(); // Read file content to a buffer. const buffer = new DataView(new ArrayBuffer(fileSize)); const readBuffer = accessHandle.read(buffer, { at: 0 }); @@ -118,10 +118,10 @@ onmessage = async (e) => { const writeBuffer = accessHandle.write(encodedMessage, { at: readBuffer }); // Persist changes to disk. - await accessHandle.flush(); + accessHandle.flush(); // Always close FileSystemSyncAccessHandle if done. - await accessHandle.close(); + accessHandle.close(); } ``` diff --git a/files/en-us/web/api/filesystemsyncaccesshandle/close/index.md b/files/en-us/web/api/filesystemsyncaccesshandle/close/index.md index ec4261bf11d5d21..a9b66b51cd72ed8 100644 --- a/files/en-us/web/api/filesystemsyncaccesshandle/close/index.md +++ b/files/en-us/web/api/filesystemsyncaccesshandle/close/index.md @@ -14,7 +14,7 @@ tags: browser-compat: api.FileSystemSyncAccessHandle.close --- -{{securecontext_header}}{{DefaultAPISidebar("File System Access API")}} +{{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. @@ -59,7 +59,7 @@ onmessage = async (e) => { const accessHandle = await draftHandle.createSyncAccessHandle(); // Get size of the file. - const fileSize = await accessHandle.getSize(); + const fileSize = accessHandle.getSize(); // Read file content to a buffer. const buffer = new DataView(new ArrayBuffer(fileSize)); const readBuffer = accessHandle.read(buffer, { at: 0 }); @@ -70,18 +70,14 @@ onmessage = async (e) => { const writeBuffer = accessHandle.write(encodedMessage, { at: readBuffer }); // Persist changes to disk. - await accessHandle.flush(); + accessHandle.flush(); // Always close FileSystemSyncAccessHandle if done. - await accessHandle.close(); + accessHandle.close(); } ``` -Note that some browsers feature an experimental synchronous version of `close()` that provides further improved performance: - -```js -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 diff --git a/files/en-us/web/api/filesystemsyncaccesshandle/flush/index.md b/files/en-us/web/api/filesystemsyncaccesshandle/flush/index.md index ee03f17cb2092cf..f851ecd1d81f3c3 100644 --- a/files/en-us/web/api/filesystemsyncaccesshandle/flush/index.md +++ b/files/en-us/web/api/filesystemsyncaccesshandle/flush/index.md @@ -14,7 +14,7 @@ tags: browser-compat: api.FileSystemSyncAccessHandle.flush --- -{{securecontext_header}}{{DefaultAPISidebar("File System Access API")}} +{{securecontext_header}}{{APIRef("File System Access API")}} The **`flush()`** method of the {{domxref("FileSystemSyncAccessHandle")}} interface persists any changes made to the file associated with the handle via the {{domxref('FileSystemSyncAccessHandle.write', 'write()')}} method to disk. @@ -59,7 +59,7 @@ onmessage = async (e) => { const accessHandle = await draftHandle.createSyncAccessHandle(); // Get size of the file. - const fileSize = await accessHandle.getSize(); + const fileSize = accessHandle.getSize(); // Read file content to a buffer. const buffer = new DataView(new ArrayBuffer(fileSize)); const readBuffer = accessHandle.read(buffer, { at: 0 }); @@ -70,18 +70,14 @@ onmessage = async (e) => { const writeBuffer = accessHandle.write(encodedMessage, { at: readBuffer }); // Persist changes to disk. - await accessHandle.flush(); + accessHandle.flush(); // Always close FileSystemSyncAccessHandle if done. - await accessHandle.close(); + accessHandle.close(); } ``` -Note that some browsers feature an experimental synchronous version of `flush()` that provides further improved performance: - -```js -accessHandle.flush(); -``` +> **Note:** In earlier versions of the spec, {{domxref("FileSystemSyncAccessHandle.close()", "close()")}}, `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 diff --git a/files/en-us/web/api/filesystemsyncaccesshandle/getsize/index.md b/files/en-us/web/api/filesystemsyncaccesshandle/getsize/index.md index 004b0fe2a5aa968..9c19d6101e1a0fe 100644 --- a/files/en-us/web/api/filesystemsyncaccesshandle/getsize/index.md +++ b/files/en-us/web/api/filesystemsyncaccesshandle/getsize/index.md @@ -14,7 +14,7 @@ tags: browser-compat: api.FileSystemSyncAccessHandle.getSize --- -{{securecontext_header}}{{DefaultAPISidebar("File System Access API")}} +{{securecontext_header}}{{APIRef("File System Access API")}} The **`getSize()`** method of the {{domxref("FileSystemSyncAccessHandle")}} interface returns the size of the file associated with the handle in bytes. @@ -60,7 +60,7 @@ onmessage = async (e) => { const accessHandle = await draftHandle.createSyncAccessHandle(); // Get size of the file. - const fileSize = await accessHandle.getSize(); + const fileSize = accessHandle.getSize(); // Read file content to a buffer. const buffer = new DataView(new ArrayBuffer(fileSize)); const readBuffer = accessHandle.read(buffer, { at: 0 }); @@ -71,18 +71,14 @@ onmessage = async (e) => { const writeBuffer = accessHandle.write(encodedMessage, { at: readBuffer }); // Persist changes to disk. - await accessHandle.flush(); + accessHandle.flush(); // Always close FileSystemSyncAccessHandle if done. - await accessHandle.close(); + accessHandle.close(); } ``` -Note that some browsers feature an experimental synchronous version of `getSize()` that provides further improved performance: - -```js -const fileSize = accessHandle.getSize(); -``` +> **Note:** In earlier versions of the spec, {{domxref("FileSystemSyncAccessHandle.close()", "close()")}}, {{domxref("FileSystemSyncAccessHandle.flush()", "flush()")}}, `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 diff --git a/files/en-us/web/api/filesystemsyncaccesshandle/index.md b/files/en-us/web/api/filesystemsyncaccesshandle/index.md index 7f16cd72fc9518e..7cdb23d0bc7b319 100644 --- a/files/en-us/web/api/filesystemsyncaccesshandle/index.md +++ b/files/en-us/web/api/filesystemsyncaccesshandle/index.md @@ -12,9 +12,11 @@ tags: browser-compat: api.FileSystemSyncAccessHandle --- -{{securecontext_header}}{{DefaultAPISidebar("File System Access API")}} +{{securecontext_header}}{{APIRef("File System Access API")}} -The **`FileSystemSyncAccessHandle`** interface of the {{domxref('File System Access API')}} represents 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). +The **`FileSystemSyncAccessHandle`** interface of the {{domxref("File System Access API", "File System Access API", "", "nocode")}} represents 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) for files within the [origin private file system](https://fs.spec.whatwg.org/#origin-private-file-system). The interface is accessed through the {{domxref('FileSystemFileHandle.createSyncAccessHandle()')}} method. @@ -61,7 +63,7 @@ onmessage = async (e) => { const accessHandle = await draftHandle.createSyncAccessHandle(); // Get size of the file. - const fileSize = await accessHandle.getSize(); + const fileSize = accessHandle.getSize(); // Read file content to a buffer. const buffer = new DataView(new ArrayBuffer(fileSize)); const readBuffer = accessHandle.read(buffer, { at: 0 }); @@ -72,21 +74,14 @@ onmessage = async (e) => { const writeBuffer = accessHandle.write(encodedMessage, { at: readBuffer }); // Persist changes to disk. - await accessHandle.flush(); + accessHandle.flush(); // Always close FileSystemSyncAccessHandle if done. - await accessHandle.close(); + accessHandle.close(); } ``` -Note that some browsers feature experimental synchronous versions of the {{domxref('FileSystemSyncAccessHandle.close', 'close()')}}, {{domxref('FileSystemSyncAccessHandle.flush', 'flush()')}}, {{domxref('FileSystemSyncAccessHandle.getSize', 'getSize()')}}, and {{domxref('FileSystemSyncAccessHandle.truncate', 'truncate()')}} methods that provide further improved performance: - -```js -accessHandle.close(); -accessHandle.flush(); -const fileSize = accessHandle.getSize(); -accessHandle.truncate(0); -``` +> **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 diff --git a/files/en-us/web/api/filesystemsyncaccesshandle/read/index.md b/files/en-us/web/api/filesystemsyncaccesshandle/read/index.md index fcb0efc8af1e0dd..7e5b2042ccba6db 100644 --- a/files/en-us/web/api/filesystemsyncaccesshandle/read/index.md +++ b/files/en-us/web/api/filesystemsyncaccesshandle/read/index.md @@ -14,7 +14,7 @@ tags: browser-compat: api.FileSystemSyncAccessHandle.read --- -{{securecontext_header}}{{DefaultAPISidebar("File System Access API")}} +{{securecontext_header}}{{APIRef("File System Access API")}} The **`read()`** method of the {{domxref("FileSystemSyncAccessHandle")}} interface reads the content of the file associated with the handle into a specified buffer, optionally at a given offset. @@ -66,7 +66,7 @@ onmessage = async (e) => { const accessHandle = await draftHandle.createSyncAccessHandle(); // Get size of the file. - const fileSize = await accessHandle.getSize(); + const fileSize = accessHandle.getSize(); // Read file content to a buffer. const buffer = new DataView(new ArrayBuffer(fileSize)); const readBuffer = accessHandle.read(buffer, { at: 0 }); @@ -77,13 +77,15 @@ onmessage = async (e) => { const writeBuffer = accessHandle.write(encodedMessage, { at: readBuffer }); // Persist changes to disk. - await accessHandle.flush(); + accessHandle.flush(); // Always close FileSystemSyncAccessHandle if done. - await accessHandle.close(); + 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}} diff --git a/files/en-us/web/api/filesystemsyncaccesshandle/truncate/index.md b/files/en-us/web/api/filesystemsyncaccesshandle/truncate/index.md index 256a5a85576c268..d33e5fdafffd444 100644 --- a/files/en-us/web/api/filesystemsyncaccesshandle/truncate/index.md +++ b/files/en-us/web/api/filesystemsyncaccesshandle/truncate/index.md @@ -14,7 +14,7 @@ tags: browser-compat: api.FileSystemSyncAccessHandle.truncate --- -{{securecontext_header}}{{DefaultAPISidebar("File System Access API")}} +{{securecontext_header}}{{APIRef("File System Access API")}} The **`truncate()`** method of the {{domxref("FileSystemSyncAccessHandle")}} interface resizes the file associated with the handle to a specified number of bytes. @@ -52,21 +52,17 @@ async function truncateFile() { const accessHandle = await draftHandle.createSyncAccessHandle(); // Truncate the file to 0 bytes - await accessHandle.truncate(0); + accessHandle.truncate(0); // Persist changes to disk. - await accessHandle.flush(); + accessHandle.flush(); // Always close FileSystemSyncAccessHandle if done. - await accessHandle.close(); + accessHandle.close(); } ``` -Note that some browsers feature an experimental synchronous version of `truncate()` that provides further improved performance: - -```js -accessHandle.truncate(0); -``` +> **Note:** In earlier versions of the spec, {{domxref("FileSystemSyncAccessHandle.close()", "close()")}}, {{domxref("FileSystemSyncAccessHandle.flush()", "flush()")}}, {{domxref("FileSystemSyncAccessHandle.getSize()", "getSize()")}}, and `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 diff --git a/files/en-us/web/api/filesystemsyncaccesshandle/write/index.md b/files/en-us/web/api/filesystemsyncaccesshandle/write/index.md index bcd2702e80235b9..fc365078e4dfe7c 100644 --- a/files/en-us/web/api/filesystemsyncaccesshandle/write/index.md +++ b/files/en-us/web/api/filesystemsyncaccesshandle/write/index.md @@ -14,7 +14,7 @@ tags: browser-compat: api.FileSystemSyncAccessHandle.write --- -{{securecontext_header}}{{DefaultAPISidebar("File System Access API")}} +{{securecontext_header}}{{APIRef("File System Access API")}} The **`write()`** method of the {{domxref("FileSystemSyncAccessHandle")}} interface writes the content of a specified buffer to the file associated with the handle, optionally at a given offset. @@ -66,7 +66,7 @@ onmessage = async (e) => { const accessHandle = await draftHandle.createSyncAccessHandle(); // Get size of the file. - const fileSize = await accessHandle.getSize(); + const fileSize = accessHandle.getSize(); // Read file content to a buffer. const buffer = new DataView(new ArrayBuffer(fileSize)); const readBuffer = accessHandle.read(buffer, { at: 0 }); @@ -77,13 +77,15 @@ onmessage = async (e) => { const writeBuffer = accessHandle.write(encodedMessage, { at: readBuffer }); // Persist changes to disk. - await accessHandle.flush(); + accessHandle.flush(); // Always close FileSystemSyncAccessHandle if done. - await accessHandle.close(); + 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}} From 2a359bd639020a2588adf8ff37304fdcfaca3a27 Mon Sep 17 00:00:00 2001 From: Chris Mills Date: Tue, 22 Nov 2022 08:18:43 +0000 Subject: [PATCH 18/19] more fixes for a-sully comments --- .../web/api/file_system_access_api/index.md | 22 ++++++++++--------- .../createsyncaccesshandle/index.md | 2 +- .../web/api/filesystemfilehandle/index.md | 2 ++ .../filesystemsyncaccesshandle/flush/index.md | 2 ++ .../filesystemsyncaccesshandle/write/index.md | 3 ++- 5 files changed, 19 insertions(+), 12 deletions(-) diff --git a/files/en-us/web/api/file_system_access_api/index.md b/files/en-us/web/api/file_system_access_api/index.md index fb8fba61167c9f8..5b0cda9b017031c 100644 --- a/files/en-us/web/api/file_system_access_api/index.md +++ b/files/en-us/web/api/file_system_access_api/index.md @@ -15,10 +15,6 @@ tags: browser-compat: - api.FileSystemHandle - api.FileSystemFileHandle - - api.FileSystemDirectoryHandle - - api.FileSystemSyncAccessHandle - - api.FileSystemWritableFileStream - - api.Window.showOpenFilePicker --- {{securecontext_header}}{{DefaultAPISidebar("File System Access API")}} @@ -33,17 +29,21 @@ Most of the interaction with files and directories is accomplished through handl 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')}}. -{{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. +{{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. + +> **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, then commit the changes to disk using {{domxref('FileSystemSyncAccessHandle.flush', 'flush()')}}. +- 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")}} @@ -53,7 +53,7 @@ This API opens up potential functionality the web has been lacking. Still, secur - {{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) for files within the [origin private file system](https://fs.spec.whatwg.org/#origin-private-file-system). + - : 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. @@ -205,7 +205,7 @@ onmessage = async (e) => { const accessHandle = await draftHandle.createSyncAccessHandle(); // Get size of the file. - const fileSize = await accessHandle.getSize(); + const fileSize = accessHandle.getSize(); // Read file content to a buffer. const buffer = new DataView(new ArrayBuffer(fileSize)); const readBuffer = accessHandle.read(buffer, { at: 0 }); @@ -216,13 +216,15 @@ onmessage = async (e) => { const writeBuffer = accessHandle.write(encodedMessage, { at: readBuffer }); // Persist changes to disk. - await accessHandle.flush(); + accessHandle.flush(); // Always close FileSystemSyncAccessHandle if done. - await accessHandle.close(); + 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}} diff --git a/files/en-us/web/api/filesystemfilehandle/createsyncaccesshandle/index.md b/files/en-us/web/api/filesystemfilehandle/createsyncaccesshandle/index.md index f9849050485a242..e211443b35cd34b 100644 --- a/files/en-us/web/api/filesystemfilehandle/createsyncaccesshandle/index.md +++ b/files/en-us/web/api/filesystemfilehandle/createsyncaccesshandle/index.md @@ -63,7 +63,7 @@ onmessage = async (e) => { // … // Always close FileSystemSyncAccessHandle if done. - await accessHandle.close(); + accessHandle.close(); } ``` diff --git a/files/en-us/web/api/filesystemfilehandle/index.md b/files/en-us/web/api/filesystemfilehandle/index.md index 3a5037968117890..a5771d60dc63828 100644 --- a/files/en-us/web/api/filesystemfilehandle/index.md +++ b/files/en-us/web/api/filesystemfilehandle/index.md @@ -125,6 +125,8 @@ onmessage = async (e) => { } ``` +> **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}} diff --git a/files/en-us/web/api/filesystemsyncaccesshandle/flush/index.md b/files/en-us/web/api/filesystemsyncaccesshandle/flush/index.md index f851ecd1d81f3c3..c8640b7370d2a15 100644 --- a/files/en-us/web/api/filesystemsyncaccesshandle/flush/index.md +++ b/files/en-us/web/api/filesystemsyncaccesshandle/flush/index.md @@ -19,6 +19,8 @@ browser-compat: api.FileSystemSyncAccessHandle.flush The **`flush()`** method of the {{domxref("FileSystemSyncAccessHandle")}} interface persists any changes made to the file associated with the handle via the {{domxref('FileSystemSyncAccessHandle.write', 'write()')}} method to disk. +Bear in mind that you only need to call this method 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. + ## Syntax ```js-nolint diff --git a/files/en-us/web/api/filesystemsyncaccesshandle/write/index.md b/files/en-us/web/api/filesystemsyncaccesshandle/write/index.md index fc365078e4dfe7c..c6cf684cb1db98b 100644 --- a/files/en-us/web/api/filesystemsyncaccesshandle/write/index.md +++ b/files/en-us/web/api/filesystemsyncaccesshandle/write/index.md @@ -19,6 +19,8 @@ browser-compat: api.FileSystemSyncAccessHandle.write The **`write()`** method of the {{domxref("FileSystemSyncAccessHandle")}} interface writes the content of a specified buffer to the file associated with the handle, optionally at a given offset. +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 the {{domxref("File System Access API", "File System Access API", "", "nocode")}} (e.g. {{domxref('FileSystemFileHandle.createWritable()')}}), where changes are not committed to disk until the writing stream is closed. + ## Syntax ```js-nolint @@ -31,7 +33,6 @@ write(buffer, FileSystemReadWriteOptions) - : An {{jsxref("ArrayBuffer")}} or `ArrayBufferView` (such as a {{jsxref("DataView")}}) representing the buffer to be written to the file. - `FileSystemReadWriteOptions` {{optional_inline}} - : An options object containing the following properties: - - `at` - : A number representing the offset in bytes from the start of the file that the buffer should be written at. From 66e92ef027dfaa456a1de9640143078d51b3a728 Mon Sep 17 00:00:00 2001 From: Jean-Yves Perrier Date: Mon, 5 Dec 2022 09:11:48 +0100 Subject: [PATCH 19/19] Update files/en-us/web/api/file_system_access_api/index.md --- files/en-us/web/api/file_system_access_api/index.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/files/en-us/web/api/file_system_access_api/index.md b/files/en-us/web/api/file_system_access_api/index.md index 5b0cda9b017031c..0ea7bd8a36bca4d 100644 --- a/files/en-us/web/api/file_system_access_api/index.md +++ b/files/en-us/web/api/file_system_access_api/index.md @@ -29,7 +29,7 @@ Most of the interaction with files and directories is accomplished through handl 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')}}. -{{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. +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. > **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.